libs/gil/doc/html/design/metafunctions.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>Metafunctions - 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="Examples" href="examples.html" />
  28     <link rel="prev" title="Dynamic images and image views" href="dynamic_image.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="Dynamic images and image views" href="dynamic_image.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="Examples" href="examples.html"><img src="../_static/next.png" alt="next"/></a>
  65
  66     </div>
  67
  68   <div class="section" id="metafunctions">
  69 <h1>Metafunctions</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="#homogeneous-memory-based-images" id="id2">Homogeneous memory-based images</a></li>
  74 <li><a class="reference internal" href="#packed-and-bit-aligned-images" id="id3">Packed and bit-aligned images</a></li>
  75 <li><a class="reference internal" href="#iterators-and-views" id="id4">Iterators and views</a></li>
  76 <li><a class="reference internal" href="#pixel-components" id="id5">Pixel components</a></li>
  77 <li><a class="reference internal" href="#deriving-and-manipulating-existing-types" id="id6">Deriving and manipulating existing types</a></li>
  78 <li><a class="reference internal" href="#type-traits" id="id7">Type traits</a></li>
  79 </ul>
  80 </div>
  81 <div class="section" id="overview">
  82 <h2><a class="toc-backref" href="#id1">Overview</a></h2>
  83 <p>Flexibility comes at a price. GIL types can be very long and hard to read.
  84 To address this problem, GIL provides typedefs to refer to any standard image,
  85 pixel iterator, pixel locator, pixel reference or pixel value.</p>
  86 <p>They follow this pattern:</p>
  87 <div class="highlight-c++"><div class="highlight"><pre><span class="o">*</span><span class="n">ColorSpace</span><span class="o">*</span> <span class="o">+</span> <span class="o">*</span><span class="n">BitDepth</span><span class="o">*</span> <span class="o">+</span> <span class="p">[</span><span class="s">&quot;s|f&quot;</span><span class="p">]</span> <span class="o">+</span> <span class="p">[</span><span class="s">&quot;c&quot;</span><span class="p">]</span> <span class="o">+</span> <span class="p">[</span><span class="s">&quot;_planar&quot;</span><span class="p">]</span> <span class="o">+</span> <span class="p">[</span><span class="s">&quot;_step&quot;</span><span class="p">]</span> <span class="o">+</span> <span class="o">*</span><span class="n">ClassType</span><span class="o">*</span> <span class="o">+</span> <span class="s">&quot;_t&quot;</span>
  88 </pre></div>
  89 </div>
  90 <p>where <em>ColorSpace</em> also indicates the ordering of components.</p>
  91 <p>Examples are <code class="docutils literal"><span class="pre">rgb</span></code>, <code class="docutils literal"><span class="pre">bgr</span></code>, <code class="docutils literal"><span class="pre">cmyk</span></code>, <code class="docutils literal"><span class="pre">rgba</span></code>. <em>BitDepth</em> can be, for
  92 example, <code class="docutils literal"><span class="pre">8</span></code>,``16``,``32``. By default the bits are unsigned integral type.
  93 Append <code class="docutils literal"><span class="pre">s</span></code> to the bit depth to indicate signed integral, or <code class="docutils literal"><span class="pre">f</span></code> to
  94 indicate floating point. <code class="docutils literal"><span class="pre">c</span></code> indicates object whose associated pixel
  95 reference is immutable. <code class="docutils literal"><span class="pre">_planar</span></code> indicates planar organization (as opposed
  96 to interleaved). <code class="docutils literal"><span class="pre">_step</span></code> indicates the type has a dynamic step and
  97 <em>ClassType</em> is <code class="docutils literal"><span class="pre">_image</span></code> (image, using a standard allocator), <code class="docutils literal"><span class="pre">_view</span></code>
  98 (image view), <code class="docutils literal"><span class="pre">_loc</span></code> (pixel locator), <code class="docutils literal"><span class="pre">_ptr</span></code> (pixel iterator), <code class="docutils literal"><span class="pre">_ref</span></code>
  99 (pixel reference), <code class="docutils literal"><span class="pre">_pixel</span></code> (pixel value).</p>
 100 <p>Here are examples:</p>
 101 <div class="highlight-cpp"><div class="highlight"><pre><span class="n">bgr8_image_t</span>               <span class="n">i</span><span class="p">;</span>     <span class="c1">// 8-bit unsigned (unsigned char) interleaved BGR image</span>
 102 <span class="n">cmyk16_pixel_t</span><span class="p">;</span>            <span class="n">x</span><span class="p">;</span>     <span class="c1">// 16-bit unsigned (unsigned short) CMYK pixel value;</span>
 103 <span class="n">cmyk16sc_planar_ref_t</span>      <span class="nf">p</span><span class="p">(</span><span class="n">x</span><span class="p">);</span>  <span class="c1">// const reference to a 16-bit signed integral (signed short) planar CMYK pixel x.</span>
 104 <span class="n">rgb32f_planar_step_ptr_t</span>   <span class="n">ii</span><span class="p">;</span>    <span class="c1">// step iterator to a floating point 32-bit (float) planar RGB pixel.</span>
 105 </pre></div>
 106 </div>
 107 </div>
 108 <div class="section" id="homogeneous-memory-based-images">
 109 <h2><a class="toc-backref" href="#id2">Homogeneous memory-based images</a></h2>
 110 <p>GIL provides the metafunctions that return the types of standard
 111 homogeneous memory-based GIL constructs given a channel type, a
 112 layout, and whether the construct is planar, has a step along the X
 113 direction, and is mutable:</p>
 114 <div class="highlight-cpp"><div class="highlight"><pre><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="p">,</span> <span class="kt">bool</span> <span class="n">IsPlanar</span><span class="o">=</span><span class="nb">false</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">IsMutable</span><span class="o">=</span><span class="nb">true</span><span class="o">&gt;</span>
 115 <span class="k">struct</span> <span class="n">pixel_reference_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 116
 117 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">Channel</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Layout</span><span class="o">&gt;</span>
 118 <span class="k">struct</span> <span class="n">pixel_value_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 119
 120 <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="p">,</span> <span class="kt">bool</span> <span class="n">IsPlanar</span><span class="o">=</span><span class="nb">false</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">IsStep</span><span class="o">=</span><span class="nb">false</span><span class="p">,</span>  <span class="kt">bool</span> <span class="n">IsMutable</span><span class="o">=</span><span class="nb">true</span><span class="o">&gt;</span>
 121 <span class="k">struct</span> <span class="n">iterator_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 122
 123 <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="p">,</span> <span class="kt">bool</span> <span class="n">IsPlanar</span><span class="o">=</span><span class="nb">false</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">IsXStep</span><span class="o">=</span><span class="nb">false</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">IsMutable</span><span class="o">=</span><span class="nb">true</span><span class="o">&gt;</span>
 124 <span class="k">struct</span> <span class="n">locator_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 125
 126 <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="p">,</span> <span class="kt">bool</span> <span class="n">IsPlanar</span><span class="o">=</span><span class="nb">false</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">IsXStep</span><span class="o">=</span><span class="nb">false</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">IsMutable</span><span class="o">=</span><span class="nb">true</span><span class="o">&gt;</span>
 127 <span class="k">struct</span> <span class="n">view_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 128
 129 <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="p">,</span> <span class="kt">bool</span> <span class="n">IsPlanar</span><span class="o">=</span><span class="nb">false</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="o">&gt;</span>
 130 <span class="k">struct</span> <span class="n">image_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 131
 132 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">BitField</span><span class="p">,</span> <span class="k">typename</span> <span class="n">ChannelBitSizeVector</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Layout</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="o">&gt;</span>
 133 <span class="k">struct</span> <span class="n">packed_image_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 134
 135 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">ChannelBitSizeVector</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Layout</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="o">&gt;</span>
 136 <span class="k">struct</span> <span class="n">bit_aligned_image_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 137 </pre></div>
 138 </div>
 139 </div>
 140 <div class="section" id="packed-and-bit-aligned-images">
 141 <h2><a class="toc-backref" href="#id3">Packed and bit-aligned images</a></h2>
 142 <p>There are also helper metafunctions to construct packed and
 143 bit-aligned images with up to five channels:</p>
 144 <div class="highlight-cpp"><div class="highlight"><pre><span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">BitField</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size1</span><span class="p">,</span>
 145         <span class="k">typename</span> <span class="n">Layout</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="o">&gt;</span>
 146 <span class="k">struct</span> <span class="n">packed_image1_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 147
 148 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">BitField</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size1</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size2</span><span class="p">,</span>
 149         <span class="k">typename</span> <span class="n">Layout</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="o">&gt;</span>
 150 <span class="k">struct</span> <span class="n">packed_image2_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 151
 152 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">BitField</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size1</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size2</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size3</span><span class="p">,</span>
 153         <span class="k">typename</span> <span class="n">Layout</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="o">&gt;</span>
 154 <span class="k">struct</span> <span class="n">packed_image3_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 155
 156 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">BitField</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size1</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size2</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size3</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size4</span><span class="p">,</span>
 157         <span class="k">typename</span> <span class="n">Layout</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="o">&gt;</span>
 158 <span class="k">struct</span> <span class="n">packed_image4_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 159
 160 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">BitField</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size1</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size2</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size3</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size4</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size5</span><span class="p">,</span>
 161         <span class="k">typename</span> <span class="n">Layout</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="o">&gt;</span>
 162 <span class="k">struct</span> <span class="n">packed_image5_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 163
 164 <span class="k">template</span> <span class="o">&lt;</span><span class="kt">unsigned</span> <span class="n">Size1</span><span class="p">,</span>
 165         <span class="k">typename</span> <span class="n">Layout</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="o">&gt;</span>
 166 <span class="k">struct</span> <span class="n">bit_aligned_image1_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 167
 168 <span class="k">template</span> <span class="o">&lt;</span><span class="kt">unsigned</span> <span class="n">Size1</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size2</span><span class="p">,</span>
 169         <span class="k">typename</span> <span class="n">Layout</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="o">&gt;</span>
 170 <span class="k">struct</span> <span class="n">bit_aligned_image2_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 171
 172 <span class="k">template</span> <span class="o">&lt;</span><span class="kt">unsigned</span> <span class="n">Size1</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size2</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size3</span><span class="p">,</span>
 173         <span class="k">typename</span> <span class="n">Layout</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="o">&gt;</span>
 174 <span class="k">struct</span> <span class="n">bit_aligned_image3_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 175
 176 <span class="k">template</span> <span class="o">&lt;</span><span class="kt">unsigned</span> <span class="n">Size1</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size2</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size3</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size4</span><span class="p">,</span>
 177         <span class="k">typename</span> <span class="n">Layout</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="o">&gt;</span>
 178 <span class="k">struct</span> <span class="n">bit_aligned_image4_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 179
 180 <span class="k">template</span> <span class="o">&lt;</span><span class="kt">unsigned</span> <span class="n">Size1</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size2</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size3</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size4</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">Size5</span><span class="p">,</span>
 181         <span class="k">typename</span> <span class="n">Layout</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Alloc</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="o">&gt;</span>
 182 <span class="k">struct</span> <span class="n">bit_aligned_image5_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 183 </pre></div>
 184 </div>
 185 </div>
 186 <div class="section" id="iterators-and-views">
 187 <h2><a class="toc-backref" href="#id4">Iterators and views</a></h2>
 188 <p>Here <code class="docutils literal"><span class="pre">ChannelValue</span></code> models <code class="docutils literal"><span class="pre">ChannelValueConcept</span></code>. We don&#8217;t need
 189 <code class="docutils literal"><span class="pre">IsYStep</span></code> because GIL&#8217;s memory-based locator and view already allow
 190 the vertical step to be specified dynamically. Iterators and views can
 191 be constructed from a pixel type:</p>
 192 <div class="highlight-cpp"><div class="highlight"><pre><span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">Pixel</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">IsPlanar</span><span class="o">=</span><span class="nb">false</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">IsStep</span><span class="o">=</span><span class="nb">false</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">IsMutable</span><span class="o">=</span><span class="nb">true</span><span class="o">&gt;</span>
 193 <span class="k">struct</span> <span class="n">iterator_type_from_pixel</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 194
 195 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">Pixel</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">IsPlanar</span><span class="o">=</span><span class="nb">false</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">IsStepX</span><span class="o">=</span><span class="nb">false</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">IsMutable</span><span class="o">=</span><span class="nb">true</span><span class="o">&gt;</span>
 196 <span class="k">struct</span> <span class="n">view_type_from_pixel</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 197 </pre></div>
 198 </div>
 199 <p>Using a heterogeneous pixel type will result in heterogeneous iterators and
 200 views. Types can also be constructed from horizontal iterator:</p>
 201 <div class="highlight-cpp"><div class="highlight"><pre><span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">XIterator</span><span class="o">&gt;</span>
 202 <span class="k">struct</span> <span class="n">type_from_x_iterator</span>
 203 <span class="p">{</span>
 204   <span class="k">typedef</span> <span class="p">...</span> <span class="n">step_iterator_t</span><span class="p">;</span>
 205   <span class="k">typedef</span> <span class="p">...</span> <span class="n">xy_locator_t</span><span class="p">;</span>
 206   <span class="k">typedef</span> <span class="p">...</span> <span class="n">view_t</span><span class="p">;</span>
 207 <span class="p">};</span>
 208 </pre></div>
 209 </div>
 210 </div>
 211 <div class="section" id="pixel-components">
 212 <h2><a class="toc-backref" href="#id5">Pixel components</a></h2>
 213 <p>You can get pixel-related types of any pixel-based GIL constructs (pixels,
 214 iterators, locators and views) using the following metafunctions provided by
 215 <code class="docutils literal"><span class="pre">PixelBasedConcept</span></code>, <code class="docutils literal"><span class="pre">HomogeneousPixelBasedConcept</span></code> and metafunctions
 216 built on top of them:</p>
 217 <div class="highlight-cpp"><div class="highlight"><pre><span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">T</span><span class="o">&gt;</span> <span class="k">struct</span> <span class="n">color_space_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 218 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">T</span><span class="o">&gt;</span> <span class="k">struct</span> <span class="n">channel_mapping_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 219 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">T</span><span class="o">&gt;</span> <span class="k">struct</span> <span class="n">is_planar</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 220
 221 <span class="c1">// Defined by homogeneous constructs</span>
 222 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">T</span><span class="o">&gt;</span> <span class="k">struct</span> <span class="n">channel_type</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 223 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">T</span><span class="o">&gt;</span> <span class="k">struct</span> <span class="n">num_channels</span> <span class="p">{</span> <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span> <span class="p">};</span>
 224 </pre></div>
 225 </div>
 226 </div>
 227 <div class="section" id="deriving-and-manipulating-existing-types">
 228 <h2><a class="toc-backref" href="#id6">Deriving and manipulating existing types</a></h2>
 229 <p>There are metafunctions to construct the type of a construct from an existing
 230 type by changing one or more of its properties:</p>
 231 <div class="highlight-cpp"><div class="highlight"><pre><span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">PixelReference</span><span class="p">,</span>
 232         <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="p">,</span> <span class="k">typename</span> <span class="n">IsPlanar</span><span class="p">,</span> <span class="k">typename</span> <span class="n">IsMutable</span><span class="o">&gt;</span>
 233 <span class="k">struct</span> <span class="n">derived_pixel_reference_type</span>
 234 <span class="p">{</span>
 235   <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span>  <span class="c1">// Models PixelConcept</span>
 236 <span class="p">};</span>
 237
 238 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">Iterator</span><span class="p">,</span>
 239         <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="p">,</span> <span class="k">typename</span> <span class="n">IsPlanar</span><span class="p">,</span> <span class="k">typename</span> <span class="n">IsStep</span><span class="p">,</span> <span class="k">typename</span> <span class="n">IsMutable</span><span class="o">&gt;</span>
 240 <span class="k">struct</span> <span class="n">derived_iterator_type</span>
 241 <span class="p">{</span>
 242   <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span>  <span class="c1">// Models PixelIteratorConcept</span>
 243 <span class="p">};</span>
 244
 245 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="p">,</span>
 246         <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="p">,</span> <span class="k">typename</span> <span class="n">IsPlanar</span><span class="p">,</span> <span class="k">typename</span> <span class="n">IsXStep</span><span class="p">,</span> <span class="k">typename</span> <span class="n">IsMutable</span><span class="o">&gt;</span>
 247 <span class="k">struct</span> <span class="n">derived_view_type</span>
 248 <span class="p">{</span>
 249   <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span>  <span class="c1">// Models ImageViewConcept</span>
 250 <span class="p">};</span>
 251
 252 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">Image</span><span class="p">,</span>
 253         <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="p">,</span> <span class="k">typename</span> <span class="n">IsPlanar</span><span class="o">&gt;</span>
 254 <span class="k">struct</span> <span class="n">derived_image_type</span>
 255 <span class="p">{</span>
 256   <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span>  <span class="c1">// Models ImageConcept</span>
 257 <span class="p">};</span>
 258 </pre></div>
 259 </div>
 260 <p>You can replace one or more of its properties and use <code class="docutils literal"><span class="pre">boost::use_default</span></code>
 261 for the rest. In this case <code class="docutils literal"><span class="pre">IsPlanar</span></code>, <code class="docutils literal"><span class="pre">IsStep</span></code> and <code class="docutils literal"><span class="pre">IsMutable</span></code> are
 262 MPL boolean constants. For example, here is how to create the type of a view
 263 just like <code class="docutils literal"><span class="pre">View</span></code>, but being grayscale and planar:</p>
 264 <div class="highlight-cpp"><div class="highlight"><pre><span class="k">using</span> <span class="n">VT</span> <span class="o">=</span> <span class="k">typename</span> <span class="n">derived_view_type</span><span class="o">&lt;</span><span class="n">View</span><span class="p">,</span> <span class="n">boost</span><span class="o">::</span><span class="n">use_default</span><span class="p">,</span> <span class="n">gray_t</span><span class="p">,</span> <span class="n">mpl</span><span class="o">::</span><span class="n">true_</span><span class="o">&gt;::</span><span class="n">type</span><span class="p">;</span>
 265 </pre></div>
 266 </div>
 267 </div>
 268 <div class="section" id="type-traits">
 269 <h2><a class="toc-backref" href="#id7">Type traits</a></h2>
 270 <p>These are metafunctions, some of which return integral types which can be
 271 evaluated like this:</p>
 272 <div class="highlight-cpp"><div class="highlight"><pre><span class="k">static_assert</span><span class="p">(</span><span class="n">is_planar</span><span class="o">&lt;</span><span class="n">rgb8_planar_view_t</span><span class="o">&gt;::</span><span class="n">value</span> <span class="o">==</span> <span class="nb">true</span><span class="p">,</span> <span class="s">&quot;&quot;</span><span class="p">);</span>
 273 </pre></div>
 274 </div>
 275 <p>GIL also supports type analysis metafunctions of the form:</p>
 276 <div class="highlight-cpp"><div class="highlight"><pre><span class="p">[</span><span class="n">pixel_reference</span><span class="o">/</span><span class="n">iterator</span><span class="o">/</span><span class="n">locator</span><span class="o">/</span><span class="n">view</span><span class="o">/</span><span class="n">image</span><span class="p">]</span> <span class="o">+</span> <span class="s">&quot;_is_&quot;</span> <span class="o">+</span> <span class="p">[</span><span class="n">basic</span><span class="o">/</span><span class="k">mutable</span><span class="o">/</span><span class="n">step</span><span class="p">]</span>
 277 </pre></div>
 278 </div>
 279 <p>For example:</p>
 280 <div class="highlight-cpp"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">view_is_mutable</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">value</span><span class="p">)</span>
 281 <span class="p">{</span>
 282  <span class="p">...</span>
 283 <span class="p">}</span>
 284 </pre></div>
 285 </div>
 286 <p>A <em>basic</em> GIL construct is a memory-based construct that uses the built-in GIL
 287 classes and does not have any function object to invoke upon dereferencing.
 288 For example, a simple planar or interleaved, step or non-step RGB image view
 289 is basic, but a color converted view or a virtual view is not.</p>
 290 </div>
 291 </div>
 292
 293
 294     <div class="navbar" style="text-align:right;">
 295
 296
 297       <a class="prev" title="Dynamic images and image views" href="dynamic_image.html"><img src="../_static/prev.png" alt="prev"/></a>
 298       <a class="up" title="Design Guide" href="index.html"><img src="../_static/up.png" alt="up"/></a>
 299       <a class="next" title="Examples" href="examples.html"><img src="../_static/next.png" alt="next"/></a>
 300
 301     </div>
 302     </div>
 303     <div class="footer" role="contentinfo">
 304       Last updated on 2019-12-10 00:12:10.
 305       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
 306     </div>
 307   </body>
 308 </html>