libs/gil/doc/html/design/pixel.html

   1
   2
   3 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6   <head>
   7     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   8
   9     <title>Pixel - Boost.GIL  documentation</title>
  10     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
  11     <link rel="stylesheet" href="../_static/style.css" type="text/css" />
  12     <script type="text/javascript">
  13       var DOCUMENTATION_OPTIONS = {
  14           URL_ROOT:    '../',
  15           VERSION:     '',
  16           COLLAPSE_MODINDEX: false,
  17           FILE_SUFFIX: '.html'
  18       };
  19     </script>
  20     <script type="text/javascript" src="../_static/jquery.js"></script>
  21     <script type="text/javascript" src="../_static/underscore.js"></script>
  22     <script type="text/javascript" src="../_static/doctools.js"></script>
  23     <link rel="index" title="Index" href="../genindex.html" />
  24     <link rel="search" title="Search" href="../search.html" />
  25     <link rel="top" title="Boost.GIL  documentation" href="../index.html" />
  26     <link rel="up" title="Design Guide" href="index.html" />
  27     <link rel="next" title="Pixel Iterator" href="pixel_iterator.html" />
  28     <link rel="prev" title="Color Base" href="color_base.html" />
  29   </head>
  30   <body>
  31     <div class="header">
  32     <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  33     "header">
  34       <tr>
  35         <td valign="top" width="300">
  36           <h3><a href="../index.html"><img
  37           alt="C++ Boost" src="../_static/gil.png" border="0"></a></h3>
  38         </td>
  39
  40         <td >
  41           <h1 align="center"><a href="../index.html"></a></h1>
  42         </td>
  43         <td>
  44       <div id="searchbox" style="display: none">
  45         <form class="search" action="../search.html" method="get">
  46           <input type="text" name="q" size="18" />
  47           <input type="submit" value="Search" />
  48           <input type="hidden" name="check_keywords" value="yes" />
  49           <input type="hidden" name="area" value="default" />
  50         </form>
  51       </div>
  52       <script type="text/javascript">$('#searchbox').show(0);</script>
  53         </td>
  54       </tr>
  55     </table>
  56     </div>
  57     <hr/>
  58     <div class="content">
  59     <div class="navbar" style="text-align:right;">
  60
  61
  62       <a class="prev" title="Color Base" href="color_base.html"><img src="../_static/prev.png" alt="prev"/></a>
  63       <a class="up" title="Design Guide" href="index.html"><img src="../_static/up.png" alt="up"/></a>
  64       <a class="next" title="Pixel Iterator" href="pixel_iterator.html"><img src="../_static/next.png" alt="next"/></a>
  65
  66     </div>
  67
  68   <div class="section" id="pixel">
  69 <h1>Pixel</h1>
  70 <div class="contents local topic" id="contents">
  71 <ul class="simple">
  72 <li><a class="reference internal" href="#overview" id="id1">Overview</a></li>
  73 <li><a class="reference internal" href="#models" id="id2">Models</a></li>
  74 <li><a class="reference internal" href="#algorithms" id="id3">Algorithms</a></li>
  75 </ul>
  76 </div>
  77 <div class="section" id="overview">
  78 <h2><a class="toc-backref" href="#id1">Overview</a></h2>
  79 <p>A pixel is a set of channels defining the color at a given point in an
  80 image. Conceptually, a pixel is little more than a color base whose
  81 elements model <code class="docutils literal"><span class="pre">ChannelConcept</span></code>. All properties of pixels inherit
  82 from color bases: pixels may be <em>homogeneous</em> if all of their channels
  83 have the same type; otherwise they are called <em>heterogeneous</em>. The
  84 channels of a pixel may be addressed using semantic or physical
  85 indexing, or by color; all color-base algorithms work on pixels as
  86 well. Two pixels are <em>compatible</em> if their color spaces are the same
  87 and their channels, paired semantically, are compatible. Note that
  88 constness, memory organization and reference/value are ignored. For
  89 example, an 8-bit RGB planar reference is compatible to a constant
  90 8-bit BGR interleaved pixel value. Most pairwise pixel operations
  91 (copy construction, assignment, equality, etc.) are only defined for
  92 compatible pixels.</p>
  93 <p>Pixels (as well as other GIL constructs built on pixels, such as
  94 iterators, locators, views and images) must provide metafunctions to
  95 access their color space, channel mapping, number of channels, and
  96 (for homogeneous pixels) the channel type:</p>
  97 <div class="highlight-cpp"><div class="highlight"><pre><span class="n">concept</span> <span class="n">PixelBasedConcept</span><span class="o">&lt;</span><span class="k">typename</span> <span class="n">T</span><span class="o">&gt;</span>
  98 <span class="p">{</span>
  99   <span class="k">typename</span> <span class="n">color_space_type</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span><span class="p">;</span>
 100       <span class="n">where</span> <span class="n">Metafunction</span><span class="o">&lt;</span><span class="n">color_space_type</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span> <span class="o">&gt;</span><span class="p">;</span>
 101       <span class="n">where</span> <span class="n">ColorSpaceConcept</span><span class="o">&lt;</span><span class="n">color_space_type</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;::</span><span class="n">type</span><span class="o">&gt;</span><span class="p">;</span>
 102   <span class="k">typename</span> <span class="n">channel_mapping_type</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span><span class="p">;</span>
 103       <span class="n">where</span> <span class="n">Metafunction</span><span class="o">&lt;</span><span class="n">channel_mapping_type</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span> <span class="o">&gt;</span><span class="p">;</span>
 104       <span class="n">where</span> <span class="n">ChannelMappingConcept</span><span class="o">&lt;</span><span class="n">channel_mapping_type</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;::</span><span class="n">type</span><span class="o">&gt;</span><span class="p">;</span>
 105   <span class="k">typename</span> <span class="n">is_planar</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span><span class="p">;</span>
 106       <span class="n">where</span> <span class="n">Metafunction</span><span class="o">&lt;</span><span class="n">is_planar</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span> <span class="o">&gt;</span><span class="p">;</span>
 107       <span class="n">where</span> <span class="n">SameType</span><span class="o">&lt;</span><span class="n">is_planar</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;::</span><span class="n">type</span><span class="p">,</span> <span class="kt">bool</span><span class="o">&gt;</span><span class="p">;</span>
 108 <span class="p">};</span>
 109
 110 <span class="n">concept</span> <span class="n">HomogeneousPixelBasedConcept</span><span class="o">&lt;</span><span class="n">PixelBasedConcept</span> <span class="n">T</span><span class="o">&gt;</span>
 111 <span class="p">{</span>
 112   <span class="k">typename</span> <span class="n">channel_type</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span><span class="p">;</span>
 113       <span class="n">where</span> <span class="n">Metafunction</span><span class="o">&lt;</span><span class="n">channel_type</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span> <span class="o">&gt;</span><span class="p">;</span>
 114       <span class="n">where</span> <span class="n">ChannelConcept</span><span class="o">&lt;</span><span class="n">channel_type</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;::</span><span class="n">type</span><span class="o">&gt;</span><span class="p">;</span>
 115 <span class="p">};</span>
 116 </pre></div>
 117 </div>
 118 <p>Pixels model the following concepts:</p>
 119 <div class="highlight-cpp"><div class="highlight"><pre><span class="n">concept</span> <span class="n">PixelConcept</span><span class="o">&lt;</span><span class="k">typename</span> <span class="n">P</span><span class="o">&gt;</span> <span class="o">:</span> <span class="n">ColorBaseConcept</span><span class="o">&lt;</span><span class="n">P</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">PixelBasedConcept</span><span class="o">&lt;</span><span class="n">P</span><span class="o">&gt;</span>
 120 <span class="p">{</span>
 121   <span class="n">where</span> <span class="n">is_pixel</span><span class="o">&lt;</span><span class="n">P</span><span class="o">&gt;::</span><span class="n">value</span><span class="o">==</span><span class="nb">true</span><span class="p">;</span>
 122   <span class="c1">// where for each K [0..size&lt;P&gt;::value-1]:</span>
 123   <span class="c1">//      ChannelConcept&lt;kth_element_type&lt;K&gt; &gt;;</span>
 124
 125   <span class="k">typename</span> <span class="n">value_type</span><span class="p">;</span>       <span class="n">where</span> <span class="n">PixelValueConcept</span><span class="o">&lt;</span><span class="n">value_type</span><span class="o">&gt;</span><span class="p">;</span>
 126   <span class="k">typename</span> <span class="n">reference</span><span class="p">;</span>        <span class="n">where</span> <span class="n">PixelConcept</span><span class="o">&lt;</span><span class="n">reference</span><span class="o">&gt;</span><span class="p">;</span>
 127   <span class="k">typename</span> <span class="n">const_reference</span><span class="p">;</span>  <span class="n">where</span> <span class="n">PixelConcept</span><span class="o">&lt;</span><span class="n">const_reference</span><span class="o">&gt;</span><span class="p">;</span>
 128   <span class="k">static</span> <span class="k">const</span> <span class="kt">bool</span> <span class="n">P</span><span class="o">::</span><span class="n">is_mutable</span><span class="p">;</span>
 129
 130   <span class="k">template</span> <span class="o">&lt;</span><span class="n">PixelConcept</span> <span class="n">P2</span><span class="o">&gt;</span> <span class="n">where</span> <span class="p">{</span> <span class="n">PixelConcept</span><span class="o">&lt;</span><span class="n">P</span><span class="p">,</span><span class="n">P2</span><span class="o">&gt;</span> <span class="p">}</span>
 131       <span class="n">P</span><span class="o">::</span><span class="n">P</span><span class="p">(</span><span class="n">P2</span><span class="p">);</span>
 132   <span class="k">template</span> <span class="o">&lt;</span><span class="n">PixelConcept</span> <span class="n">P2</span><span class="o">&gt;</span> <span class="n">where</span> <span class="p">{</span> <span class="n">PixelConcept</span><span class="o">&lt;</span><span class="n">P</span><span class="p">,</span><span class="n">P2</span><span class="o">&gt;</span> <span class="p">}</span>
 133       <span class="kt">bool</span> <span class="k">operator</span><span class="o">==</span><span class="p">(</span><span class="k">const</span> <span class="n">P</span><span class="o">&amp;</span><span class="p">,</span> <span class="k">const</span> <span class="n">P2</span><span class="o">&amp;</span><span class="p">);</span>
 134   <span class="k">template</span> <span class="o">&lt;</span><span class="n">PixelConcept</span> <span class="n">P2</span><span class="o">&gt;</span> <span class="n">where</span> <span class="p">{</span> <span class="n">PixelConcept</span><span class="o">&lt;</span><span class="n">P</span><span class="p">,</span><span class="n">P2</span><span class="o">&gt;</span> <span class="p">}</span>
 135       <span class="kt">bool</span> <span class="k">operator</span><span class="o">!=</span><span class="p">(</span><span class="k">const</span> <span class="n">P</span><span class="o">&amp;</span><span class="p">,</span> <span class="k">const</span> <span class="n">P2</span><span class="o">&amp;</span><span class="p">);</span>
 136 <span class="p">};</span>
 137
 138 <span class="n">concept</span> <span class="n">MutablePixelConcept</span><span class="o">&lt;</span><span class="k">typename</span> <span class="n">P</span><span class="o">&gt;</span> <span class="o">:</span> <span class="n">PixelConcept</span><span class="o">&lt;</span><span class="n">P</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">MutableColorBaseConcept</span><span class="o">&lt;</span><span class="n">P</span><span class="o">&gt;</span>
 139 <span class="p">{</span>
 140   <span class="n">where</span> <span class="n">is_mutable</span><span class="o">==</span><span class="nb">true</span><span class="p">;</span>
 141 <span class="p">};</span>
 142
 143 <span class="n">concept</span> <span class="n">HomogeneousPixelConcept</span><span class="o">&lt;</span><span class="n">PixelConcept</span> <span class="n">P</span><span class="o">&gt;</span> <span class="o">:</span> <span class="n">HomogeneousColorBaseConcept</span><span class="o">&lt;</span><span class="n">P</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">HomogeneousPixelBasedConcept</span><span class="o">&lt;</span><span class="n">P</span><span class="o">&gt;</span>
 144 <span class="p">{</span>
 145   <span class="n">P</span><span class="o">::</span><span class="k">template</span> <span class="n">element_const_reference_type</span><span class="o">&lt;</span><span class="n">P</span><span class="o">&gt;::</span><span class="n">type</span> <span class="k">operator</span><span class="p">[](</span><span class="n">P</span> <span class="n">p</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">i</span><span class="p">)</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="n">dynamic_at_c</span><span class="p">(</span><span class="n">P</span><span class="p">,</span><span class="n">i</span><span class="p">);</span> <span class="p">}</span>
 146 <span class="p">};</span>
 147
 148 <span class="n">concept</span> <span class="n">MutableHomogeneousPixelConcept</span><span class="o">&lt;</span><span class="n">MutablePixelConcept</span> <span class="n">P</span><span class="o">&gt;</span> <span class="o">:</span> <span class="n">MutableHomogeneousColorBaseConcept</span><span class="o">&lt;</span><span class="n">P</span><span class="o">&gt;</span>
 149 <span class="p">{</span>
 150   <span class="n">P</span><span class="o">::</span><span class="k">template</span> <span class="n">element_reference_type</span><span class="o">&lt;</span><span class="n">P</span><span class="o">&gt;::</span><span class="n">type</span> <span class="k">operator</span><span class="p">[](</span><span class="n">P</span> <span class="n">p</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">i</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">dynamic_at_c</span><span class="p">(</span><span class="n">p</span><span class="p">,</span><span class="n">i</span><span class="p">);</span> <span class="p">}</span>
 151 <span class="p">};</span>
 152
 153 <span class="n">concept</span> <span class="n">PixelValueConcept</span><span class="o">&lt;</span><span class="k">typename</span> <span class="n">P</span><span class="o">&gt;</span> <span class="o">:</span> <span class="n">PixelConcept</span><span class="o">&lt;</span><span class="n">P</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">Regular</span><span class="o">&lt;</span><span class="n">P</span><span class="o">&gt;</span>
 154 <span class="p">{</span>
 155   <span class="n">where</span> <span class="n">SameType</span><span class="o">&lt;</span><span class="n">value_type</span><span class="p">,</span><span class="n">P</span><span class="o">&gt;</span><span class="p">;</span>
 156 <span class="p">};</span>
 157
 158 <span class="n">concept</span> <span class="n">PixelsCompatibleConcept</span><span class="o">&lt;</span><span class="n">PixelConcept</span> <span class="n">P1</span><span class="p">,</span> <span class="n">PixelConcept</span> <span class="n">P2</span><span class="o">&gt;</span> <span class="o">:</span> <span class="n">ColorBasesCompatibleConcept</span><span class="o">&lt;</span><span class="n">P1</span><span class="p">,</span><span class="n">P2</span><span class="o">&gt;</span>
 159 <span class="p">{</span>
 160   <span class="c1">// where for each K [0..size&lt;P1&gt;::value):</span>
 161   <span class="c1">//    ChannelsCompatibleConcept&lt;kth_semantic_element_type&lt;P1,K&gt;::type, kth_semantic_element_type&lt;P2,K&gt;::type&gt;;</span>
 162 <span class="p">};</span>
 163 </pre></div>
 164 </div>
 165 <p>A pixel is <em>convertible</em> to a second pixel if it is possible to
 166 approximate its color in the form of the second pixel. Conversion is
 167 an explicit, non-symmetric and often lossy operation (due to both
 168 channel and color space approximation). Convertibility requires
 169 modeling the following concept:</p>
 170 <div class="highlight-cpp"><div class="highlight"><pre><span class="k">template</span> <span class="o">&lt;</span><span class="n">PixelConcept</span> <span class="n">SrcPixel</span><span class="p">,</span> <span class="n">MutablePixelConcept</span> <span class="n">DstPixel</span><span class="o">&gt;</span>
 171 <span class="n">concept</span> <span class="n">PixelConvertibleConcept</span>
 172 <span class="p">{</span>
 173   <span class="kt">void</span> <span class="n">color_convert</span><span class="p">(</span><span class="k">const</span> <span class="n">SrcPixel</span><span class="o">&amp;</span><span class="p">,</span> <span class="n">DstPixel</span><span class="o">&amp;</span><span class="p">);</span>
 174 <span class="p">};</span>
 175 </pre></div>
 176 </div>
 177 <p>The distinction between <code class="docutils literal"><span class="pre">PixelConcept</span></code> and <code class="docutils literal"><span class="pre">PixelValueConcept</span></code> is
 178 analogous to that for channels and color bases - pixel reference proxies model
 179 both, but only pixel values model the latter.</p>
 180 <div class="admonition seealso">
 181 <p class="first admonition-title">See also</p>
 182 <ul class="last simple">
 183 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_pixel_based_concept.html">PixelBasedConcept&lt;P&gt;</a></li>
 184 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_pixel_concept.html">PixelConcept&lt;Pixel&gt;</a></li>
 185 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_mutable_pixel_concept.html">MutablePixelConcept&lt;Pixel&gt;</a></li>
 186 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_pixel_value_concept.html">PixelValueConcept&lt;Pixel&gt;</a></li>
 187 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_homogeneous_pixel_based_concept.html">HomogeneousPixelConcept&lt;Pixel&gt;</a></li>
 188 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_mutable_homogeneous_pixel_concept.html">MutableHomogeneousPixelConcept&lt;Pixel&gt;</a></li>
 189 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_homogeneous_pixel_value_concept.html">HomogeneousPixelValueConcept&lt;Pixel&gt;</a></li>
 190 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_pixels_compatible_concept.html">PixelsCompatibleConcept&lt;Pixel1, Pixel2&gt;</a></li>
 191 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_pixel_convertible_concept.html">PixelConvertibleConcept&lt;SrcPixel, DstPixel&gt;</a></li>
 192 </ul>
 193 </div>
 194 </div>
 195 <div class="section" id="models">
 196 <h2><a class="toc-backref" href="#id2">Models</a></h2>
 197 <p>The most commonly used pixel is a homogeneous pixel whose values are
 198 together in memory. For this purpose GIL provides the struct
 199 <code class="docutils literal"><span class="pre">pixel</span></code>, templated over the channel value and layout:</p>
 200 <div class="highlight-cpp"><div class="highlight"><pre><span class="c1">// models HomogeneousPixelValueConcept</span>
 201 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">ChannelValue</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Layout</span><span class="o">&gt;</span> <span class="k">struct</span> <span class="n">pixel</span><span class="p">;</span>
 202
 203 <span class="c1">// Those typedefs are already provided by GIL</span>
 204 <span class="k">typedef</span> <span class="n">pixel</span><span class="o">&lt;</span><span class="n">bits8</span><span class="p">,</span> <span class="n">rgb_layout_t</span><span class="o">&gt;</span> <span class="n">rgb8_pixel_t</span><span class="p">;</span>
 205 <span class="k">typedef</span> <span class="n">pixel</span><span class="o">&lt;</span><span class="n">bits8</span><span class="p">,</span> <span class="n">bgr_layout_t</span><span class="o">&gt;</span> <span class="n">bgr8_pixel_t</span><span class="p">;</span>
 206
 207 <span class="n">bgr8_pixel_t</span> <span class="nf">bgr8</span><span class="p">(</span><span class="mi">255</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">);</span>     <span class="c1">// pixels can be initialized with the channels directly</span>
 208 <span class="n">rgb8_pixel_t</span> <span class="nf">rgb8</span><span class="p">(</span><span class="n">bgr8</span><span class="p">);</span>        <span class="c1">// compatible pixels can also be copy-constructed</span>
 209
 210 <span class="n">rgb8</span> <span class="o">=</span> <span class="n">bgr8</span><span class="p">;</span>            <span class="c1">// assignment and equality is defined between compatible pixels</span>
 211 <span class="n">assert</span><span class="p">(</span><span class="n">rgb8</span> <span class="o">==</span> <span class="n">bgr8</span><span class="p">);</span>   <span class="c1">// assignment and equality operate on the semantic channels</span>
 212
 213 <span class="c1">// The first physical channels of the two pixels are different</span>
 214 <span class="n">assert</span><span class="p">(</span><span class="n">at_c</span><span class="o">&lt;</span><span class="mi">0</span><span class="o">&gt;</span><span class="p">(</span><span class="n">rgb8</span><span class="p">)</span> <span class="o">!=</span> <span class="n">at_c</span><span class="o">&lt;</span><span class="mi">0</span><span class="o">&gt;</span><span class="p">(</span><span class="n">bgr8</span><span class="p">));</span>
 215 <span class="n">assert</span><span class="p">(</span><span class="n">dynamic_at_c</span><span class="p">(</span><span class="n">bgr8</span><span class="p">,</span><span class="mi">0</span><span class="p">)</span> <span class="o">!=</span> <span class="n">dynamic_at_c</span><span class="p">(</span><span class="n">rgb8</span><span class="p">,</span><span class="mi">0</span><span class="p">));</span>
 216 <span class="n">assert</span><span class="p">(</span><span class="n">rgb8</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">!=</span> <span class="n">bgr8</span><span class="p">[</span><span class="mi">0</span><span class="p">]);</span> <span class="c1">// same as above (but operator[] is defined for pixels only)</span>
 217 </pre></div>
 218 </div>
 219 <p>Planar pixels have their channels distributed in memory. While they share the
 220 same value type (<code class="docutils literal"><span class="pre">pixel</span></code>) with interleaved pixels, their reference type is a
 221 proxy class containing references to each of the channels.
 222 This is implemented with the struct <code class="docutils literal"><span class="pre">planar_pixel_reference</span></code>:</p>
 223 <div class="highlight-cpp"><div class="highlight"><pre><span class="c1">// models HomogeneousPixel</span>
 224 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">ChannelReference</span><span class="p">,</span> <span class="k">typename</span> <span class="n">ColorSpace</span><span class="o">&gt;</span> <span class="k">struct</span> <span class="n">planar_pixel_reference</span><span class="p">;</span>
 225
 226 <span class="c1">// Define the type of a mutable and read-only reference. (These typedefs are already provided by GIL)</span>
 227 <span class="k">typedef</span> <span class="n">planar_pixel_reference</span><span class="o">&lt;</span>      <span class="n">bits8</span><span class="o">&amp;</span><span class="p">,</span><span class="n">rgb_t</span><span class="o">&gt;</span> <span class="n">rgb8_planar_ref_t</span><span class="p">;</span>
 228 <span class="k">typedef</span> <span class="n">planar_pixel_reference</span><span class="o">&lt;</span><span class="k">const</span> <span class="n">bits8</span><span class="o">&amp;</span><span class="p">,</span><span class="n">rgb_t</span><span class="o">&gt;</span> <span class="n">rgb8c_planar_ref_t</span><span class="p">;</span>
 229 </pre></div>
 230 </div>
 231 <p>Note that, unlike the <code class="docutils literal"><span class="pre">pixel</span></code> struct, planar pixel references are templated
 232 over the color space, not over the pixel layout. They always use a canonical
 233 channel ordering. Ordering of their elements is unnecessary because their
 234 elements are references to the channels.</p>
 235 <p>Sometimes the channels of a pixel may not be byte-aligned. For example an RGB
 236 pixel in &#8216;5-5-6&#8217; format is a 16-bit pixel whose red, green and blue channels
 237 occupy bits [0..4],[5..9] and [10..15] respectively. GIL provides a model for
 238 such packed pixel formats:</p>
 239 <div class="highlight-cpp"><div class="highlight"><pre><span class="c1">// define an rgb565 pixel</span>
 240 <span class="k">typedef</span> <span class="n">packed_pixel_type</span><span class="o">&lt;</span><span class="kt">uint16_t</span><span class="p">,</span> <span class="n">mpl</span><span class="o">::</span><span class="n">vector3_c</span><span class="o">&lt;</span><span class="kt">unsigned</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">6</span><span class="p">,</span><span class="mi">5</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">rgb_layout_t</span><span class="o">&gt;::</span><span class="n">type</span> <span class="n">rgb565_pixel_t</span><span class="p">;</span>
 241
 242 <span class="n">function_requires</span><span class="o">&lt;</span><span class="n">PixelValueConcept</span><span class="o">&lt;</span><span class="n">rgb565_pixel_t</span><span class="o">&gt;</span> <span class="o">&gt;</span><span class="p">();</span>
 243 <span class="k">static_assert</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">rgb565_pixel_t</span><span class="p">)</span> <span class="o">==</span> <span class="mi">2</span><span class="p">,</span> <span class="s">&quot;&quot;</span><span class="p">);</span>
 244
 245 <span class="c1">// define a bgr556 pixel</span>
 246 <span class="k">typedef</span> <span class="n">packed_pixel_type</span><span class="o">&lt;</span><span class="kt">uint16_t</span><span class="p">,</span> <span class="n">mpl</span><span class="o">::</span><span class="n">vector3_c</span><span class="o">&lt;</span><span class="kt">unsigned</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">6</span><span class="p">,</span><span class="mi">5</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">bgr_layout_t</span><span class="o">&gt;::</span><span class="n">type</span> <span class="n">bgr556_pixel_t</span><span class="p">;</span>
 247
 248 <span class="n">function_requires</span><span class="o">&lt;</span><span class="n">PixelValueConcept</span><span class="o">&lt;</span><span class="n">bgr556_pixel_t</span><span class="o">&gt;</span> <span class="o">&gt;</span><span class="p">();</span>
 249
 250 <span class="c1">// rgb565 is compatible with bgr556.</span>
 251 <span class="n">function_requires</span><span class="o">&lt;</span><span class="n">PixelsCompatibleConcept</span><span class="o">&lt;</span><span class="n">rgb565_pixel_t</span><span class="p">,</span><span class="n">bgr556_pixel_t</span><span class="o">&gt;</span> <span class="o">&gt;</span><span class="p">();</span>
 252 </pre></div>
 253 </div>
 254 <p>In some cases, the pixel itself may not be byte aligned. For example,
 255 consider an RGB pixel in &#8216;2-3-2&#8217; format. Its size is 7 bits. GIL
 256 refers to such pixels, pixel iterators and images as
 257 &#8220;bit-aligned&#8221;. Bit-aligned pixels (and images) are more complex than
 258 packed ones. Since packed pixels are byte-aligned, we can use a C++
 259 reference as the reference type to a packed pixel, and a C pointer as
 260 an x_iterator over a row of packed pixels. For bit-aligned constructs
 261 we need a special reference proxy class (bit_aligned_pixel_reference)
 262 and iterator class (bit_aligned_pixel_iterator). The value type of
 263 bit-aligned pixels is a packed_pixel. Here is how to use bit_aligned
 264 pixels and pixel iterators:</p>
 265 <div class="highlight-cpp"><div class="highlight"><pre><span class="c1">// Mutable reference to a BGR232 pixel</span>
 266 <span class="k">typedef</span> <span class="k">const</span> <span class="n">bit_aligned_pixel_reference</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="p">,</span> <span class="n">mpl</span><span class="o">::</span><span class="n">vector3_c</span><span class="o">&lt;</span><span class="kt">unsigned</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">bgr_layout_t</span><span class="p">,</span> <span class="nb">true</span><span class="o">&gt;</span>  <span class="n">bgr232_ref_t</span><span class="p">;</span>
 267
 268 <span class="c1">// A mutable iterator over BGR232 pixels</span>
 269 <span class="k">typedef</span> <span class="n">bit_aligned_pixel_iterator</span><span class="o">&lt;</span><span class="n">bgr232_ref_t</span><span class="o">&gt;</span> <span class="n">bgr232_ptr_t</span><span class="p">;</span>
 270
 271 <span class="c1">// BGR232 pixel value. It is a packed_pixel of size 1 byte. (The last bit is unused)</span>
 272 <span class="k">typedef</span> <span class="n">std</span><span class="o">::</span><span class="n">iterator_traits</span><span class="o">&lt;</span><span class="n">bgr232_ptr_t</span><span class="o">&gt;::</span><span class="n">value_type</span> <span class="n">bgr232_pixel_t</span><span class="p">;</span>
 273 <span class="k">static_assert</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">bgr232_pixel_t</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span><span class="p">,</span> <span class="s">&quot;&quot;</span><span class="p">);</span>
 274
 275 <span class="n">bgr232_pixel_t</span> <span class="nf">red</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">);</span> <span class="c1">// = 0RRGGGBB, = 01100000 = 0x60</span>
 276
 277 <span class="c1">// a buffer of 7 bytes fits exactly 8 BGR232 pixels.</span>
 278 <span class="kt">unsigned</span> <span class="kt">char</span> <span class="n">pix_buffer</span><span class="p">[</span><span class="mi">7</span><span class="p">];</span>
 279 <span class="n">std</span><span class="o">::</span><span class="n">fill</span><span class="p">(</span><span class="n">pix_buffer</span><span class="p">,</span><span class="n">pix_buffer</span><span class="o">+</span><span class="mi">7</span><span class="p">,</span><span class="mi">0</span><span class="p">);</span>
 280
 281 <span class="c1">// Fill the 8 pixels with red</span>
 282 <span class="n">bgr232_ptr_t</span> <span class="nf">pix_it</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pix_buffer</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span><span class="mi">0</span><span class="p">);</span>  <span class="c1">// start at bit 0 of the first pixel</span>
 283 <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="n">i</span><span class="o">&lt;</span><span class="mi">8</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
 284 <span class="p">{</span>
 285   <span class="o">*</span><span class="n">pix_it</span><span class="o">++</span> <span class="o">=</span> <span class="n">red</span><span class="p">;</span>
 286 <span class="p">}</span>
 287 <span class="c1">// Result: 0x60 0x30 0x11 0x0C 0x06 0x83 0xC1</span>
 288 </pre></div>
 289 </div>
 290 </div>
 291 <div class="section" id="algorithms">
 292 <h2><a class="toc-backref" href="#id3">Algorithms</a></h2>
 293 <p>Since pixels model <code class="docutils literal"><span class="pre">ColorBaseConcept</span></code> and <code class="docutils literal"><span class="pre">PixelBasedConcept</span></code> all
 294 algorithms and metafunctions of color bases can work with them as well:</p>
 295 <div class="highlight-cpp"><div class="highlight"><pre><span class="c1">// This is how to access the first semantic channel (red)</span>
 296 <span class="n">assert</span><span class="p">(</span><span class="n">semantic_at_c</span><span class="o">&lt;</span><span class="mi">0</span><span class="o">&gt;</span><span class="p">(</span><span class="n">rgb8</span><span class="p">)</span> <span class="o">==</span> <span class="n">semantic_at_c</span><span class="o">&lt;</span><span class="mi">0</span><span class="o">&gt;</span><span class="p">(</span><span class="n">bgr8</span><span class="p">));</span>
 297
 298 <span class="c1">// This is how to access the red channel by name</span>
 299 <span class="n">assert</span><span class="p">(</span><span class="n">get_color</span><span class="o">&lt;</span><span class="n">red_t</span><span class="o">&gt;</span><span class="p">(</span><span class="n">rgb8</span><span class="p">)</span> <span class="o">==</span> <span class="n">get_color</span><span class="o">&lt;</span><span class="n">red_t</span><span class="o">&gt;</span><span class="p">(</span><span class="n">bgr8</span><span class="p">));</span>
 300
 301 <span class="c1">// This is another way of doing it (some compilers don&#39;t like the first one)</span>
 302 <span class="n">assert</span><span class="p">(</span><span class="n">get_color</span><span class="p">(</span><span class="n">rgb8</span><span class="p">,</span><span class="n">red_t</span><span class="p">())</span> <span class="o">==</span> <span class="n">get_color</span><span class="p">(</span><span class="n">bgr8</span><span class="p">,</span><span class="n">red_t</span><span class="p">()));</span>
 303
 304 <span class="c1">// This is how to use the PixelBasedConcept metafunctions</span>
 305 <span class="n">BOOST_MPL_ASSERT</span><span class="p">(</span><span class="n">num_channels</span><span class="o">&lt;</span><span class="n">rgb8_pixel_t</span><span class="o">&gt;::</span><span class="n">value</span> <span class="o">==</span> <span class="mi">3</span><span class="p">);</span>
 306 <span class="n">BOOST_MPL_ASSERT</span><span class="p">((</span><span class="n">is_same</span><span class="o">&lt;</span><span class="n">channel_type</span><span class="o">&lt;</span><span class="n">rgb8_pixel_t</span><span class="o">&gt;::</span><span class="n">type</span><span class="p">,</span> <span class="n">bits8</span><span class="o">&gt;</span><span class="p">));</span>
 307 <span class="n">BOOST_MPL_ASSERT</span><span class="p">((</span><span class="n">is_same</span><span class="o">&lt;</span><span class="n">color_space_type</span><span class="o">&lt;</span><span class="n">bgr8_pixel_t</span><span class="o">&gt;::</span><span class="n">type</span><span class="p">,</span> <span class="n">rgb_t</span><span class="o">&gt;</span> <span class="p">));</span>
 308 <span class="n">BOOST_MPL_ASSERT</span><span class="p">((</span><span class="n">is_same</span><span class="o">&lt;</span><span class="n">channel_mapping_type</span><span class="o">&lt;</span><span class="n">bgr8_pixel_t</span><span class="o">&gt;::</span><span class="n">type</span><span class="p">,</span> <span class="n">mpl</span><span class="o">::</span><span class="n">vector3_c</span><span class="o">&lt;</span><span class="kt">int</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="o">&gt;</span> <span class="o">&gt;</span> <span class="p">));</span>
 309
 310 <span class="c1">// Pixels contain just the three channels and nothing extra</span>
 311 <span class="n">BOOST_MPL_ASSERT</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">rgb8_pixel_t</span><span class="p">)</span><span class="o">==</span><span class="mi">3</span><span class="p">);</span>
 312
 313 <span class="n">rgb8_planar_ref_t</span> <span class="nf">ref</span><span class="p">(</span><span class="n">bgr8</span><span class="p">);</span>    <span class="c1">// copy construction is allowed from a compatible mutable pixel type</span>
 314
 315 <span class="n">get_color</span><span class="o">&lt;</span><span class="n">red_t</span><span class="o">&gt;</span><span class="p">(</span><span class="n">ref</span><span class="p">)</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span>     <span class="c1">// assignment is ok because the reference is mutable</span>
 316 <span class="n">assert</span><span class="p">(</span><span class="n">get_color</span><span class="o">&lt;</span><span class="n">red_t</span><span class="o">&gt;</span><span class="p">(</span><span class="n">bgr8</span><span class="p">)</span><span class="o">==</span><span class="mi">10</span><span class="p">);</span>  <span class="c1">// references modify the value they are bound to</span>
 317
 318 <span class="c1">// Create a zero packed pixel and a full regular unpacked pixel.</span>
 319 <span class="n">rgb565_pixel_t</span> <span class="n">r565</span><span class="p">;</span>
 320 <span class="n">rgb8_pixel_t</span> <span class="nf">rgb_full</span><span class="p">(</span><span class="mi">255</span><span class="p">,</span><span class="mi">255</span><span class="p">,</span><span class="mi">255</span><span class="p">);</span>
 321
 322 <span class="c1">// Convert all channels of the unpacked pixel to the packed one &amp; assert the packed one is full</span>
 323 <span class="n">get_color</span><span class="p">(</span><span class="n">r565</span><span class="p">,</span><span class="n">red_t</span><span class="p">())</span>   <span class="o">=</span> <span class="n">channel_convert</span><span class="o">&lt;</span><span class="n">rgb565_channel0_t</span><span class="o">&gt;</span><span class="p">(</span><span class="n">get_color</span><span class="p">(</span><span class="n">rgb_full</span><span class="p">,</span><span class="n">red_t</span><span class="p">()));</span>
 324 <span class="n">get_color</span><span class="p">(</span><span class="n">r565</span><span class="p">,</span><span class="n">green_t</span><span class="p">())</span> <span class="o">=</span> <span class="n">channel_convert</span><span class="o">&lt;</span><span class="n">rgb565_channel1_t</span><span class="o">&gt;</span><span class="p">(</span><span class="n">get_color</span><span class="p">(</span><span class="n">rgb_full</span><span class="p">,</span><span class="n">green_t</span><span class="p">()));</span>
 325 <span class="n">get_color</span><span class="p">(</span><span class="n">r565</span><span class="p">,</span><span class="n">blue_t</span><span class="p">())</span>  <span class="o">=</span> <span class="n">channel_convert</span><span class="o">&lt;</span><span class="n">rgb565_channel2_t</span><span class="o">&gt;</span><span class="p">(</span><span class="n">get_color</span><span class="p">(</span><span class="n">rgb_full</span><span class="p">,</span><span class="n">blue_t</span><span class="p">()));</span>
 326 <span class="n">assert</span><span class="p">(</span><span class="n">r565</span> <span class="o">==</span> <span class="n">rgb565_pixel_t</span><span class="p">((</span><span class="kt">uint16_t</span><span class="p">)</span><span class="mi">65535</span><span class="p">));</span>
 327 </pre></div>
 328 </div>
 329 <p>GIL also provides the <code class="docutils literal"><span class="pre">color_convert</span></code> algorithm to convert between pixels of
 330 different color spaces and channel types:</p>
 331 <div class="highlight-cpp"><div class="highlight"><pre><span class="n">rgb8_pixel_t</span> <span class="nf">red_in_rgb8</span><span class="p">(</span><span class="mi">255</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">);</span>
 332 <span class="n">cmyk16_pixel_t</span> <span class="n">red_in_cmyk16</span><span class="p">;</span>
 333 <span class="n">color_convert</span><span class="p">(</span><span class="n">red_in_rgb8</span><span class="p">,</span><span class="n">red_in_cmyk16</span><span class="p">);</span>
 334 </pre></div>
 335 </div>
 336 </div>
 337 </div>
 338
 339
 340     <div class="navbar" style="text-align:right;">
 341
 342
 343       <a class="prev" title="Color Base" href="color_base.html"><img src="../_static/prev.png" alt="prev"/></a>
 344       <a class="up" title="Design Guide" href="index.html"><img src="../_static/up.png" alt="up"/></a>
 345       <a class="next" title="Pixel Iterator" href="pixel_iterator.html"><img src="../_static/next.png" alt="next"/></a>
 346
 347     </div>
 348     </div>
 349     <div class="footer" role="contentinfo">
 350       Last updated on 2019-12-10 00:12:10.
 351       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
 352     </div>
 353   </body>
 354 </html>