libs/gil/doc/html/design/extending.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>Extending - 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="Conclusions" href="conclusions.html" />
  28     <link rel="prev" title="Technicalities" href="technicalities.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="Technicalities" href="technicalities.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="Conclusions" href="conclusions.html"><img src="../_static/next.png" alt="next"/></a>
  65
  66     </div>
  67
  68   <div class="section" id="extending">
  69 <h1>Extending</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="#defining-new-color-spaces" id="id2">Defining new color spaces</a></li>
  74 <li><a class="reference internal" href="#defining-new-channel-types" id="id3">Defining new channel types</a></li>
  75 <li><a class="reference internal" href="#overloading-color-conversion" id="id4">Overloading color conversion</a></li>
  76 <li><a class="reference internal" href="#defining-new-image-views" id="id5">Defining new image views</a></li>
  77 </ul>
  78 </div>
  79 <div class="section" id="overview">
  80 <h2><a class="toc-backref" href="#id1">Overview</a></h2>
  81 <p>You can define your own pixel iterators, locators, image views,
  82 images, channel types, color spaces and algorithms. You can make
  83 virtual images that live on the disk, inside a jpeg file, somewhere on
  84 the internet, or even fully-synthetic images such as the Mandelbrot
  85 set. As long as they properly model the corresponding concepts, they
  86 will work with any existing GIL code. Most such extensions require no
  87 changes to the library and can thus be supplied in another module.</p>
  88 </div>
  89 <div class="section" id="defining-new-color-spaces">
  90 <h2><a class="toc-backref" href="#id2">Defining new color spaces</a></h2>
  91 <p>Each color space is in a separate file. To add a new color space, just
  92 copy one of the existing ones (like rgb.hpp) and change it
  93 accordingly. If you want color conversion support, you will have to
  94 provide methods to convert between it and the existing color spaces
  95 (see color_convert.h). For convenience you may want to provide useful
  96 typedefs for pixels, pointers, references and images with the new
  97 color space (see typedefs.h).</p>
  98 </div>
  99 <div class="section" id="defining-new-channel-types">
 100 <h2><a class="toc-backref" href="#id3">Defining new channel types</a></h2>
 101 <p>Most of the time you don&#8217;t need to do anything special to use a new
 102 channel type. You can just use it:</p>
 103 <div class="highlight-cpp"><div class="highlight"><pre><span class="k">typedef</span> <span class="n">pixel</span><span class="o">&lt;</span><span class="kt">double</span><span class="p">,</span><span class="n">rgb_layout_t</span><span class="o">&gt;</span>   <span class="n">rgb64_pixel_t</span><span class="p">;</span>    <span class="c1">// 64 bit RGB pixel</span>
 104 <span class="k">typedef</span> <span class="n">rgb64_pixel</span><span class="o">*</span>                 <span class="n">rgb64_pixel_ptr_t</span><span class="p">;</span><span class="c1">// pointer to 64-bit interleaved data</span>
 105 <span class="k">typedef</span> <span class="n">image_type</span><span class="o">&lt;</span><span class="kt">double</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">rgb64_image_t</span><span class="p">;</span>    <span class="c1">// 64-bit interleaved image</span>
 106 </pre></div>
 107 </div>
 108 <p>If you want to use your own channel class, you will need to provide a
 109 specialization of <code class="docutils literal"><span class="pre">channel_traits</span></code> for it (see channel.hpp). If you
 110 want to do conversion between your and existing channel types, you
 111 will need to provide an overload of <code class="docutils literal"><span class="pre">channel_convert</span></code>.</p>
 112 </div>
 113 <div class="section" id="overloading-color-conversion">
 114 <h2><a class="toc-backref" href="#id4">Overloading color conversion</a></h2>
 115 <p>Suppose you want to provide your own color conversion. For example,
 116 you may want to implement higher quality color conversion using color
 117 profiles. Typically you may want to redefine color conversion only in
 118 some instances and default to GIL&#8217;s color conversion in all other
 119 cases. Here is, for example, how to overload color conversion so that
 120 color conversion to gray inverts the result but everything else
 121 remains the same:</p>
 122 <div class="highlight-cpp"><div class="highlight"><pre><span class="c1">// make the default use GIL&#39;s default</span>
 123 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">SrcColorSpace</span><span class="p">,</span> <span class="k">typename</span> <span class="n">DstColorSpace</span><span class="o">&gt;</span>
 124 <span class="k">struct</span> <span class="nl">my_color_converter_impl</span>
 125 <span class="p">:</span> <span class="k">public</span> <span class="n">default_color_converter_impl</span><span class="o">&lt;</span><span class="n">SrcColorSpace</span><span class="p">,</span><span class="n">DstColorSpace</span><span class="o">&gt;</span> <span class="p">{};</span>
 126
 127 <span class="c1">// provide specializations only for cases you care about</span>
 128 <span class="c1">// (in this case, if the destination is grayscale, invert it)</span>
 129 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">SrcColorSpace</span><span class="o">&gt;</span>
 130 <span class="k">struct</span> <span class="n">my_color_converter_impl</span><span class="o">&lt;</span><span class="n">SrcColorSpace</span><span class="p">,</span><span class="n">gray_t</span><span class="o">&gt;</span>
 131 <span class="p">{</span>
 132   <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">SrcP</span><span class="p">,</span> <span class="k">typename</span> <span class="n">DstP</span><span class="o">&gt;</span>  <span class="c1">// Model PixelConcept</span>
 133   <span class="kt">void</span> <span class="k">operator</span><span class="p">()(</span><span class="k">const</span> <span class="n">SrcP</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">,</span> <span class="n">DstP</span><span class="o">&amp;</span> <span class="n">dst</span><span class="p">)</span> <span class="k">const</span>
 134   <span class="p">{</span>
 135       <span class="n">default_color_converter_impl</span><span class="o">&lt;</span><span class="n">SrcColorSpace</span><span class="p">,</span><span class="n">gray_t</span><span class="o">&gt;</span><span class="p">()(</span><span class="n">src</span><span class="p">,</span><span class="n">dst</span><span class="p">);</span>
 136       <span class="n">get_color</span><span class="p">(</span><span class="n">dst</span><span class="p">,</span><span class="n">gray_color_t</span><span class="p">())</span><span class="o">=</span><span class="n">channel_invert</span><span class="p">(</span><span class="n">get_color</span><span class="p">(</span><span class="n">dst</span><span class="p">,</span><span class="n">gray_color_t</span><span class="p">()));</span>
 137   <span class="p">}</span>
 138 <span class="p">};</span>
 139
 140 <span class="c1">// create a color converter object that dispatches to your own implementation</span>
 141 <span class="k">struct</span> <span class="n">my_color_converter</span>
 142 <span class="p">{</span>
 143   <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">SrcP</span><span class="p">,</span> <span class="k">typename</span> <span class="n">DstP</span><span class="o">&gt;</span>  <span class="c1">// Model PixelConcept</span>
 144   <span class="kt">void</span> <span class="k">operator</span><span class="p">()(</span><span class="k">const</span> <span class="n">SrcP</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">,</span><span class="n">DstP</span><span class="o">&amp;</span> <span class="n">dst</span><span class="p">)</span> <span class="k">const</span>
 145   <span class="p">{</span>
 146       <span class="k">typedef</span> <span class="k">typename</span> <span class="n">color_space_type</span><span class="o">&lt;</span><span class="n">SrcP</span><span class="o">&gt;::</span><span class="n">type</span> <span class="n">SrcColorSpace</span><span class="p">;</span>
 147       <span class="k">typedef</span> <span class="k">typename</span> <span class="n">color_space_type</span><span class="o">&lt;</span><span class="n">DstP</span><span class="o">&gt;::</span><span class="n">type</span> <span class="n">DstColorSpace</span><span class="p">;</span>
 148       <span class="n">my_color_converter_impl</span><span class="o">&lt;</span><span class="n">SrcColorSpace</span><span class="p">,</span><span class="n">DstColorSpace</span><span class="o">&gt;</span><span class="p">()(</span><span class="n">src</span><span class="p">,</span><span class="n">dst</span><span class="p">);</span>
 149   <span class="p">}</span>
 150 <span class="p">};</span>
 151 </pre></div>
 152 </div>
 153 <p>GIL color conversion functions take the color converter as an
 154 optional parameter. You can pass your own color converter:</p>
 155 <div class="highlight-cpp"><div class="highlight"><pre><span class="n">color_converted_view</span><span class="o">&lt;</span><span class="n">gray8_pixel_t</span><span class="o">&gt;</span><span class="p">(</span><span class="n">img_view</span><span class="p">,</span><span class="n">my_color_converter</span><span class="p">());</span>
 156 </pre></div>
 157 </div>
 158 </div>
 159 <div class="section" id="defining-new-image-views">
 160 <h2><a class="toc-backref" href="#id5">Defining new image views</a></h2>
 161 <p>You can provide your own pixel iterators, locators and views,
 162 overriding either the mechanism for getting from one pixel to the next
 163 or doing an arbitrary pixel transformation on dereference. For
 164 example, let&#8217;s look at the implementation of <code class="docutils literal"><span class="pre">color_converted_view</span></code>
 165 (an image factory method that, given any image view, returns a new,
 166 otherwise identical view, except that color conversion is performed on
 167 pixel access). First we need to define a model of
 168 <code class="docutils literal"><span class="pre">PixelDereferenceAdaptorConcept</span></code>; a function object that will be
 169 called when we dereference a pixel iterator. It will call
 170 <code class="docutils literal"><span class="pre">color_convert</span></code> to convert to the destination pixel type:</p>
 171 <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">SrcConstRefP</span><span class="p">,</span>  <span class="c1">// const reference to the source pixel</span>
 172         <span class="k">typename</span> <span class="n">DstP</span><span class="o">&gt;</span>          <span class="c1">// Destination pixel value (models PixelValueConcept)</span>
 173 <span class="k">class</span> <span class="nc">color_convert_deref_fn</span>
 174 <span class="p">{</span>
 175 <span class="k">public</span><span class="o">:</span>
 176   <span class="k">typedef</span> <span class="n">color_convert_deref_fn</span> <span class="n">const_t</span><span class="p">;</span>
 177   <span class="k">typedef</span> <span class="n">DstP</span>                <span class="n">value_type</span><span class="p">;</span>
 178   <span class="k">typedef</span> <span class="n">value_type</span>          <span class="n">reference</span><span class="p">;</span>      <span class="c1">// read-only dereferencing</span>
 179   <span class="k">typedef</span> <span class="k">const</span> <span class="n">value_type</span><span class="o">&amp;</span>   <span class="n">const_reference</span><span class="p">;</span>
 180   <span class="k">typedef</span> <span class="n">SrcConstRefP</span>        <span class="n">argument_type</span><span class="p">;</span>
 181   <span class="k">typedef</span> <span class="n">reference</span>           <span class="n">result_type</span><span class="p">;</span>
 182   <span class="k">static</span> <span class="kt">bool</span> <span class="k">constexpr</span> <span class="n">is_mutable</span> <span class="o">=</span> <span class="nb">false</span><span class="p">;</span>
 183
 184   <span class="n">result_type</span> <span class="nf">operator</span><span class="p">()(</span><span class="n">argument_type</span> <span class="n">srcP</span><span class="p">)</span> <span class="k">const</span> <span class="p">{</span>
 185       <span class="n">result_type</span> <span class="n">dstP</span><span class="p">;</span>
 186       <span class="n">color_convert</span><span class="p">(</span><span class="n">srcP</span><span class="p">,</span><span class="n">dstP</span><span class="p">);</span>
 187       <span class="k">return</span> <span class="n">dstP</span><span class="p">;</span>
 188   <span class="p">}</span>
 189 <span class="p">};</span>
 190 </pre></div>
 191 </div>
 192 <p>We then use the <code class="docutils literal"><span class="pre">add_deref</span></code> member struct of image views to construct the
 193 type of a view that invokes a given function object (<code class="docutils literal"><span class="pre">deref_t</span></code>) upon
 194 dereferencing. In our case, it performs color conversion:</p>
 195 <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">SrcView</span><span class="p">,</span> <span class="k">typename</span> <span class="n">DstP</span><span class="o">&gt;</span>
 196 <span class="k">struct</span> <span class="n">color_converted_view_type</span>
 197 <span class="p">{</span>
 198 <span class="k">private</span><span class="o">:</span>
 199   <span class="k">typedef</span> <span class="k">typename</span> <span class="n">SrcView</span><span class="o">::</span><span class="n">const_t</span><span class="o">::</span><span class="n">reference</span> <span class="n">src_pix_ref</span><span class="p">;</span>  <span class="c1">// const reference to pixel in SrcView</span>
 200   <span class="k">typedef</span> <span class="n">color_convert_deref_fn</span><span class="o">&lt;</span><span class="n">src_pix_ref</span><span class="p">,</span> <span class="n">DstP</span><span class="o">&gt;</span> <span class="n">deref_t</span><span class="p">;</span> <span class="c1">// the dereference adaptor that performs color conversion</span>
 201   <span class="k">typedef</span> <span class="k">typename</span> <span class="n">SrcView</span><span class="o">::</span><span class="k">template</span> <span class="n">add_deref</span><span class="o">&lt;</span><span class="n">deref_t</span><span class="o">&gt;</span> <span class="n">add_ref_t</span><span class="p">;</span>
 202 <span class="k">public</span><span class="o">:</span>
 203   <span class="k">typedef</span> <span class="k">typename</span> <span class="n">add_ref_t</span><span class="o">::</span><span class="n">type</span> <span class="n">type</span><span class="p">;</span> <span class="c1">// the color converted view type</span>
 204   <span class="k">static</span> <span class="n">type</span> <span class="nf">make</span><span class="p">(</span><span class="k">const</span> <span class="n">SrcView</span><span class="o">&amp;</span> <span class="n">sv</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">add_ref_t</span><span class="o">::</span><span class="n">make</span><span class="p">(</span><span class="n">sv</span><span class="p">,</span> <span class="n">deref_t</span><span class="p">());</span> <span class="p">}</span>
 205 <span class="p">};</span>
 206 </pre></div>
 207 </div>
 208 <p>Finally our <code class="docutils literal"><span class="pre">color_converted_view</span></code> code simply creates color-converted view
 209 from the source view:</p>
 210 <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">DstP</span><span class="p">,</span> <span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span> <span class="kr">inline</span>
 211 <span class="k">typename</span> <span class="n">color_converted_view_type</span><span class="o">&lt;</span><span class="n">View</span><span class="p">,</span><span class="n">DstP</span><span class="o">&gt;::</span><span class="n">type</span> <span class="n">color_convert_view</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">)</span>
 212 <span class="p">{</span>
 213   <span class="k">return</span> <span class="n">color_converted_view_type</span><span class="o">&lt;</span><span class="n">View</span><span class="p">,</span><span class="n">DstP</span><span class="o">&gt;::</span><span class="n">make</span><span class="p">(</span><span class="n">src</span><span class="p">);</span>
 214 <span class="p">}</span>
 215 </pre></div>
 216 </div>
 217 <p>(The actual color convert view transformation is slightly more
 218 complicated, as it takes an optional color conversion object, which
 219 allows users to specify their own color conversion methods). See the
 220 GIL tutorial for an example of creating a virtual image view that
 221 defines the Mandelbrot set.</p>
 222 </div>
 223 </div>
 224
 225
 226     <div class="navbar" style="text-align:right;">
 227
 228
 229       <a class="prev" title="Technicalities" href="technicalities.html"><img src="../_static/prev.png" alt="prev"/></a>
 230       <a class="up" title="Design Guide" href="index.html"><img src="../_static/up.png" alt="up"/></a>
 231       <a class="next" title="Conclusions" href="conclusions.html"><img src="../_static/next.png" alt="next"/></a>
 232
 233     </div>
 234     </div>
 235     <div class="footer" role="contentinfo">
 236       Last updated on 2019-12-10 00:12:10.
 237       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
 238     </div>
 239   </body>
 240 </html>