Home Explore Help
Register Sign In
devn00b
/
EQ2EMu
9
3
Fork 0
Files Issues 59 Pull Requests 0 Wiki
Tree: 9574459e57
Branches Tags
EQ2EMu
/
EQ2
/
source
/
depends
/
boost_1_72_0
/
libs
/
gil
/
doc
/
html
/
design
/
dynamic_image.html

dynamic_image.html 37 KB
History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338 
  1. 

  2. 

  3. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    4. 

  4.   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    5. 

  5. <html xmlns="http://www.w3.org/1999/xhtml">
    6. 

  6.   <head>
    7. 

  7.     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    8. 

  8.     
    9. 

  9.     <title>Dynamic images and image views - Boost.GIL  documentation</title>
    10. 

  10.     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    11. 

  11.     <link rel="stylesheet" href="../_static/style.css" type="text/css" />
    12. 

  12.     <script type="text/javascript">
    13. 

  13.       var DOCUMENTATION_OPTIONS = {
    14. 

  14.           URL_ROOT:    '../',
    15. 

  15.           VERSION:     '',
    16. 

  16.           COLLAPSE_MODINDEX: false,
    17. 

  17.           FILE_SUFFIX: '.html'
    18. 

  18.       };
    19. 

  19.     </script>
    20. 

  20.     <script type="text/javascript" src="../_static/jquery.js"></script>
    21. 

  21.     <script type="text/javascript" src="../_static/underscore.js"></script>
    22. 

  22.     <script type="text/javascript" src="../_static/doctools.js"></script>
    23. 

  23.     <link rel="index" title="Index" href="../genindex.html" />
    24. 

  24.     <link rel="search" title="Search" href="../search.html" />
    25. 

  25.     <link rel="top" title="Boost.GIL  documentation" href="../index.html" />
    26. 

  26.     <link rel="up" title="Design Guide" href="index.html" />
    27. 

  27.     <link rel="next" title="Metafunctions" href="metafunctions.html" />
    28. 

  28.     <link rel="prev" title="Image" href="image.html" /> 
    29. 

  29.   </head>
    30. 

  30.   <body>
    31. 

  31.     <div class="header">
    32. 

  32.     <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
    33. 

  33.     "header">
    34. 

  34.       <tr>
    35. 

  35.         <td valign="top" width="300">
    36. 

  36.           <h3><a href="../index.html"><img
    37. 

  37.           alt="C++ Boost" src="../_static/gil.png" border="0"></a></h3>
    38. 

  38.         </td>
    39. 

  39. 

  40.         <td >
    41. 

  41.           <h1 align="center"><a href="../index.html"></a></h1>
    42. 

  42.         </td>
    43. 

  43. 	<td>
    44. 

  44.       <div id="searchbox" style="display: none">
    45. 

  45.         <form class="search" action="../search.html" method="get">
    46. 

  46.           <input type="text" name="q" size="18" />
    47. 

  47.           <input type="submit" value="Search" />
    48. 

  48.           <input type="hidden" name="check_keywords" value="yes" />
    49. 

  49.           <input type="hidden" name="area" value="default" />
    50. 

  50.         </form>
    51. 

  51.       </div>
    52. 

  52.       <script type="text/javascript">$('#searchbox').show(0);</script>
    53. 

  53. 	</td>
    54. 

  54.       </tr>
    55. 

  55.     </table>
    56. 

  56.     </div>
    57. 

  57.     <hr/>
    58. 

  58.     <div class="content">
    59. 

  59.     <div class="navbar" style="text-align:right;">
    60. 

  60.       
    61. 

  61.       
    62. 

  62.       <a class="prev" title="Image" href="image.html"><img src="../_static/prev.png" alt="prev"/></a>
    63. 

  63.       <a class="up" title="Design Guide" href="index.html"><img src="../_static/up.png" alt="up"/></a>
    64. 

  64.       <a class="next" title="Metafunctions" href="metafunctions.html"><img src="../_static/next.png" alt="next"/></a>
    65. 

  65.       
    66. 

  66.     </div>
    67. 

  67.       
    68. 

  68.   <div class="section" id="dynamic-images-and-image-views">
    69. 

  69. <h1>Dynamic images and image views</h1>
    70. 

  70. <p>The GIL extension called <code class="docutils literal"><span class="pre">dynamic_image</span></code> allows for images, image views
    71. 

  71. or any GIL constructs to have their parameters defined at run time.</p>
    72. 

  72. <p>The color space, channel depth, channel ordering, and interleaved/planar
    73. 

  73. structure of an image are defined by the type of its template argument, which
    74. 

  74. makes them compile-time bound. Often some of these parameters are available
    75. 

  75. only at run time. Consider, for example, writing a module that opens the image
    76. 

  76. at a given file path, rotates it and saves it back in its original color space
    77. 

  77. and channel depth. How can we possibly write this using our generic image?
    78. 

  78. What type is the image loading code supposed to return?</p>
    79. 

  79. <p>Here is an example:</p>
    80. 

  80. <div class="highlight-cpp"><div class="highlight"><pre><span class="cp">#include</span> <span class="cpf">&lt;boost/gil/extension/dynamic_image/dynamic_image_all.hpp&gt;</span><span class="cp"></span>
    81. 

  81. <span class="k">using</span> <span class="k">namespace</span> <span class="n">boost</span><span class="p">;</span>
    82. 

  82. 

  83. <span class="cp">#define ASSERT_SAME(A,B) static_assert(is_same&lt; A,B &gt;::value, &quot;&quot;)</span>
    84. 

  84. 

  85. <span class="c1">// Define the set of allowed images</span>
    86. 

  86. <span class="k">typedef</span> <span class="n">mpl</span><span class="o">::</span><span class="n">vector</span><span class="o">&lt;</span><span class="n">rgb8_image_t</span><span class="p">,</span> <span class="n">cmyk16_planar_image_t</span><span class="o">&gt;</span> <span class="n">my_images_t</span><span class="p">;</span>
    87. 

  87. 

  88. <span class="c1">// Create any_image class (or any_image_view) class</span>
    89. 

  89. <span class="k">typedef</span> <span class="n">any_image</span><span class="o">&lt;</span><span class="n">my_images_t</span><span class="o">&gt;</span> <span class="n">my_any_image_t</span><span class="p">;</span>
    90. 

  90. 

  91. <span class="c1">// Associated view types are available (equivalent to the ones in image_t)</span>
    92. 

  92. <span class="k">typedef</span> <span class="n">any_image_view</span><span class="o">&lt;</span><span class="n">mpl</span><span class="o">::</span><span class="n">vector2</span><span class="o">&lt;</span><span class="n">rgb8_view_t</span><span class="p">,</span>  <span class="n">cmyk16_planar_view_t</span> <span class="o">&gt;</span> <span class="o">&gt;</span> <span class="n">AV</span><span class="p">;</span>
    93. 

  93. <span class="n">ASSERT_SAME</span><span class="p">(</span><span class="n">my_any_image_t</span><span class="o">::</span><span class="n">view_t</span><span class="p">,</span> <span class="n">AV</span><span class="p">);</span>
    94. 

  94. 

  95. <span class="k">typedef</span> <span class="n">any_image_view</span><span class="o">&lt;</span><span class="n">mpl</span><span class="o">::</span><span class="n">vector2</span><span class="o">&lt;</span><span class="n">rgb8c_view_t</span><span class="p">,</span> <span class="n">cmyk16c_planar_view_t</span><span class="o">&gt;</span> <span class="o">&gt;</span> <span class="n">CAV</span><span class="p">;</span>
    96. 

  96. <span class="n">ASSERT_SAME</span><span class="p">(</span><span class="n">my_any_image_t</span><span class="o">::</span><span class="n">const_view_t</span><span class="p">,</span> <span class="n">CAV</span><span class="p">);</span>
    97. 

  97. <span class="n">ASSERT_SAME</span><span class="p">(</span><span class="n">my_any_image_t</span><span class="o">::</span><span class="n">const_view_t</span><span class="p">,</span> <span class="n">my_any_image_t</span><span class="o">::</span><span class="n">view_t</span><span class="o">::</span><span class="n">const_t</span><span class="p">);</span>
    98. 

  98. 

  99. <span class="k">typedef</span> <span class="n">any_image_view</span><span class="o">&lt;</span><span class="n">mpl</span><span class="o">::</span><span class="n">vector2</span><span class="o">&lt;</span><span class="n">rgb8_step_view_t</span><span class="p">,</span> <span class="n">cmyk16_planar_step_view_t</span><span class="o">&gt;</span> <span class="o">&gt;</span> <span class="n">SAV</span><span class="p">;</span>
    100. 

  100. <span class="n">ASSERT_SAME</span><span class="p">(</span><span class="k">typename</span> <span class="n">dynamic_x_step_type</span><span class="o">&lt;</span><span class="n">my_any_image_t</span><span class="o">::</span><span class="n">view_t</span><span class="o">&gt;::</span><span class="n">type</span><span class="p">,</span> <span class="n">SAV</span><span class="p">);</span>
    101. 

  101. 

  102. <span class="c1">// Assign it a concrete image at run time:</span>
    103. 

  103. <span class="n">my_any_image_t</span> <span class="n">myImg</span> <span class="o">=</span> <span class="n">my_any_image_t</span><span class="p">(</span><span class="n">rgb8_image_t</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span><span class="mi">100</span><span class="p">));</span>
    104. 

  104. 

  105. <span class="c1">// Change it to another at run time. The previous image gets destroyed</span>
    106. 

  106. <span class="n">myImg</span> <span class="o">=</span> <span class="n">cmyk16_planar_image_t</span><span class="p">(</span><span class="mi">200</span><span class="p">,</span><span class="mi">100</span><span class="p">);</span>
    107. 

  107. 

  108. <span class="c1">// Assigning to an image not in the allowed set throws an exception</span>
    109. 

  109. <span class="n">myImg</span> <span class="o">=</span> <span class="n">gray8_image_t</span><span class="p">();</span>        <span class="c1">// will throw std::bad_cast</span>
    110. 

  110. </pre></div>
    111. 

  111. </div>
    112. 

  112. <p>The <code class="docutils literal"><span class="pre">any_image</span></code> and <code class="docutils literal"><span class="pre">any_image_view</span></code> subclass from GIL <code class="docutils literal"><span class="pre">variant</span></code> class,
    113. 

  113. which breaks down the instantiated type into a non-templated underlying base
    114. 

  114. type and a unique instantiation type identifier. The underlying base instance
    115. 

  115. is represented as a block of bytes.
    116. 

  116. The block is large enough to hold the largest of the specified types.</p>
    117. 

  117. <p>GIL variant is similar to <code class="docutils literal"><span class="pre">boost::variant</span></code> in spirit (hence we borrow the
    118. 

  118. name from there) but it differs in several ways from the current boost
    119. 

  119. implementation. Perhaps the biggest difference is that GIL variant always
    120. 

  120. takes a single argument, which is a model of MPL Random Access Sequence
    121. 

  121. enumerating the allowed types. Having a single interface allows GIL variant
    122. 

  122. to be used easier in generic code. Synopsis:</p>
    123. 

  123. <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">Types</span><span class="o">&gt;</span>    <span class="c1">// models MPL Random Access Container</span>
    124. 

  124. <span class="k">class</span> <span class="nc">variant</span>
    125. 

  125. <span class="p">{</span>
    126. 

  126.   <span class="p">...</span>         <span class="n">_bits</span><span class="p">;</span>
    127. 

  127.   <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">_index</span><span class="p">;</span>
    128. 

  128. <span class="k">public</span><span class="o">:</span>
    129. 

  129.   <span class="k">typedef</span> <span class="n">Types</span> <span class="n">types_t</span><span class="p">;</span>
    130. 

  130. 

  131.   <span class="n">variant</span><span class="p">();</span>
    132. 

  132.   <span class="n">variant</span><span class="p">(</span><span class="k">const</span> <span class="n">variant</span><span class="o">&amp;</span> <span class="n">v</span><span class="p">);</span>
    133. 

  133.   <span class="k">virtual</span> <span class="o">~</span><span class="n">variant</span><span class="p">();</span>
    134. 

  134. 

  135.   <span class="n">variant</span><span class="o">&amp;</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span><span class="k">const</span> <span class="n">variant</span><span class="o">&amp;</span> <span class="n">v</span><span class="p">);</span>
    136. 

  136.   <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">TS</span><span class="o">&gt;</span> <span class="k">friend</span> <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">variant</span><span class="o">&lt;</span><span class="n">TS</span><span class="o">&gt;&amp;</span> <span class="n">x</span><span class="p">,</span> <span class="k">const</span> <span class="n">variant</span><span class="o">&lt;</span><span class="n">TS</span><span class="o">&gt;&amp;</span> <span class="n">y</span><span class="p">);</span>
    137. 

  137.   <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">TS</span><span class="o">&gt;</span> <span class="k">friend</span> <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">variant</span><span class="o">&lt;</span><span class="n">TS</span><span class="o">&gt;&amp;</span> <span class="n">x</span><span class="p">,</span> <span class="k">const</span> <span class="n">variant</span><span class="o">&lt;</span><span class="n">TS</span><span class="o">&gt;&amp;</span> <span class="n">y</span><span class="p">);</span>
    138. 

  138. 

  139.   <span class="c1">// Construct/assign to type T. Throws std::bad_cast if T is not in Types</span>
    140. 

  140.   <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">explicit</span> <span class="n">variant</span><span class="p">(</span><span class="k">const</span> <span class="n">T</span><span class="o">&amp;</span> <span class="n">obj</span><span class="p">);</span>
    141. 

  141.   <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="n">variant</span><span class="o">&amp;</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span><span class="k">const</span> <span class="n">T</span><span class="o">&amp;</span> <span class="n">obj</span><span class="p">);</span>
    142. 

  142. 

  143.   <span class="c1">// Construct/assign by swapping T with its current instance. Only possible if they are swappable</span>
    144. 

  144.   <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">explicit</span> <span class="n">variant</span><span class="p">(</span><span class="n">T</span><span class="o">&amp;</span> <span class="n">obj</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">do_swap</span><span class="p">);</span>
    145. 

  145.   <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="kt">void</span> <span class="n">move_in</span><span class="p">(</span><span class="n">T</span><span class="o">&amp;</span> <span class="n">obj</span><span class="p">);</span>
    146. 

  146. 

  147.   <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">static</span> <span class="kt">bool</span> <span class="n">has_type</span><span class="p">();</span>
    148. 

  148. 

  149.   <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">const</span> <span class="n">T</span><span class="o">&amp;</span> <span class="n">_dynamic_cast</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
    150. 

  150.   <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="n">T</span><span class="o">&amp;</span> <span class="n">_dynamic_cast</span><span class="p">();</span>
    151. 

  151. 

  152.   <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="kt">bool</span> <span class="n">current_type_is</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
    153. 

  153. <span class="p">};</span>
    154. 

  154. 

  155. <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">UOP</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Types</span><span class="o">&gt;</span>
    156. 

  156.  <span class="n">UOP</span><span class="o">::</span><span class="n">result_type</span> <span class="n">apply_operation</span><span class="p">(</span><span class="n">variant</span><span class="o">&lt;</span><span class="n">Types</span><span class="o">&gt;&amp;</span> <span class="n">v</span><span class="p">,</span> <span class="n">UOP</span> <span class="n">op</span><span class="p">);</span>
    157. 

  157. <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">UOP</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Types</span><span class="o">&gt;</span>
    158. 

  158.  <span class="n">UOP</span><span class="o">::</span><span class="n">result_type</span> <span class="n">apply_operation</span><span class="p">(</span><span class="k">const</span> <span class="n">variant</span><span class="o">&lt;</span><span class="n">Types</span><span class="o">&gt;&amp;</span> <span class="n">v</span><span class="p">,</span> <span class="n">UOP</span> <span class="n">op</span><span class="p">);</span>
    159. 

  159. 

  160. <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">BOP</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Types1</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Types2</span><span class="o">&gt;</span>
    161. 

  161.  <span class="n">BOP</span><span class="o">::</span><span class="n">result_type</span> <span class="n">apply_operation</span><span class="p">(</span>      <span class="n">variant</span><span class="o">&lt;</span><span class="n">Types1</span><span class="o">&gt;&amp;</span> <span class="n">v1</span><span class="p">,</span>       <span class="n">variant</span><span class="o">&lt;</span><span class="n">Types2</span><span class="o">&gt;&amp;</span> <span class="n">v2</span><span class="p">,</span> <span class="n">UOP</span> <span class="n">op</span><span class="p">);</span>
    162. 

  162. 

  163. <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">BOP</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Types1</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Types2</span><span class="o">&gt;</span>
    164. 

  164.  <span class="n">BOP</span><span class="o">::</span><span class="n">result_type</span> <span class="n">apply_operation</span><span class="p">(</span><span class="k">const</span> <span class="n">variant</span><span class="o">&lt;</span><span class="n">Types1</span><span class="o">&gt;&amp;</span> <span class="n">v1</span><span class="p">,</span>       <span class="n">variant</span><span class="o">&lt;</span><span class="n">Types2</span><span class="o">&gt;&amp;</span> <span class="n">v2</span><span class="p">,</span> <span class="n">UOP</span> <span class="n">op</span><span class="p">);</span>
    165. 

  165. 

  166. <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">BOP</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Types1</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Types2</span><span class="o">&gt;</span>
    167. 

  167.  <span class="n">BOP</span><span class="o">::</span><span class="n">result_type</span> <span class="n">apply_operation</span><span class="p">(</span><span class="k">const</span> <span class="n">variant</span><span class="o">&lt;</span><span class="n">Types1</span><span class="o">&gt;&amp;</span> <span class="n">v1</span><span class="p">,</span> <span class="k">const</span> <span class="n">variant</span><span class="o">&lt;</span><span class="n">Types2</span><span class="o">&gt;&amp;</span> <span class="n">v2</span><span class="p">,</span> <span class="n">UOP</span> <span class="n">op</span><span class="p">);</span>
    168. 

  168. </pre></div>
    169. 

  169. </div>
    170. 

  170. <p>GIL <code class="docutils literal"><span class="pre">any_image_view</span></code> and <code class="docutils literal"><span class="pre">any_image</span></code> are subclasses of <code class="docutils literal"><span class="pre">variant</span></code>:</p>
    171. 

  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">ImageViewTypes</span><span class="o">&gt;</span>
    172. 

  172. <span class="k">class</span> <span class="nc">any_image_view</span> <span class="o">:</span> <span class="k">public</span> <span class="n">variant</span><span class="o">&lt;</span><span class="n">ImageViewTypes</span><span class="o">&gt;</span>
    173. 

  173. <span class="p">{</span>
    174. 

  174. <span class="k">public</span><span class="o">:</span>
    175. 

  175.   <span class="k">typedef</span> <span class="p">...</span> <span class="n">const_t</span><span class="p">;</span> <span class="c1">// immutable equivalent of this</span>
    176. 

  176.   <span class="k">typedef</span> <span class="n">std</span><span class="o">::</span><span class="kt">ptrdiff_t</span> <span class="n">x_coord_t</span><span class="p">;</span>
    177. 

  177.   <span class="k">typedef</span> <span class="n">std</span><span class="o">::</span><span class="kt">ptrdiff_t</span> <span class="n">y_coord_t</span><span class="p">;</span>
    178. 

  178.   <span class="k">typedef</span> <span class="n">point</span><span class="o">&lt;</span><span class="n">std</span><span class="o">::</span><span class="kt">ptrdiff_t</span><span class="o">&gt;</span> <span class="n">point_t</span><span class="p">;</span>
    179. 

  179. 

  180.   <span class="n">any_image_view</span><span class="p">();</span>
    181. 

  181.   <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">explicit</span> <span class="n">any_image_view</span><span class="p">(</span><span class="k">const</span> <span class="n">T</span><span class="o">&amp;</span> <span class="n">obj</span><span class="p">);</span>
    182. 

  182.   <span class="n">any_image_view</span><span class="p">(</span><span class="k">const</span> <span class="n">any_image_view</span><span class="o">&amp;</span> <span class="n">v</span><span class="p">);</span>
    183. 

  183. 

  184.   <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="n">any_image_view</span><span class="o">&amp;</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span><span class="k">const</span> <span class="n">T</span><span class="o">&amp;</span> <span class="n">obj</span><span class="p">);</span>
    185. 

  185.   <span class="n">any_image_view</span><span class="o">&amp;</span>                       <span class="k">operator</span><span class="o">=</span><span class="p">(</span><span class="k">const</span> <span class="n">any_image_view</span><span class="o">&amp;</span> <span class="n">v</span><span class="p">);</span>
    186. 

  186. 

  187.   <span class="c1">// parameters of the currently instantiated view</span>
    188. 

  188.   <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">num_channels</span><span class="p">()</span>  <span class="k">const</span><span class="p">;</span>
    189. 

  189.   <span class="n">point_t</span>     <span class="nf">dimensions</span><span class="p">()</span>    <span class="k">const</span><span class="p">;</span>
    190. 

  190.   <span class="n">x_coord_t</span>   <span class="nf">width</span><span class="p">()</span>         <span class="k">const</span><span class="p">;</span>
    191. 

  191.   <span class="n">y_coord_t</span>   <span class="nf">height</span><span class="p">()</span>        <span class="k">const</span><span class="p">;</span>
    192. 

  192. <span class="p">};</span>
    193. 

  193. 

  194. <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">ImageTypes</span><span class="o">&gt;</span>
    195. 

  195. <span class="k">class</span> <span class="nc">any_image</span> <span class="o">:</span> <span class="k">public</span> <span class="n">variant</span><span class="o">&lt;</span><span class="n">ImageTypes</span><span class="o">&gt;</span>
    196. 

  196. <span class="p">{</span>
    197. 

  197.   <span class="k">typedef</span> <span class="n">variant</span><span class="o">&lt;</span><span class="n">ImageTypes</span><span class="o">&gt;</span> <span class="n">parent_t</span><span class="p">;</span>
    198. 

  198. <span class="k">public</span><span class="o">:</span>
    199. 

  199.   <span class="k">typedef</span> <span class="p">...</span> <span class="n">const_view_t</span><span class="p">;</span>
    200. 

  200.   <span class="k">typedef</span> <span class="p">...</span> <span class="n">view_t</span><span class="p">;</span>
    201. 

  201.   <span class="k">typedef</span> <span class="n">std</span><span class="o">::</span><span class="kt">ptrdiff_t</span> <span class="n">x_coord_t</span><span class="p">;</span>
    202. 

  202.   <span class="k">typedef</span> <span class="n">std</span><span class="o">::</span><span class="kt">ptrdiff_t</span> <span class="n">y_coord_t</span><span class="p">;</span>
    203. 

  203.   <span class="k">typedef</span> <span class="n">point</span><span class="o">&lt;</span><span class="n">std</span><span class="o">::</span><span class="kt">ptrdiff_t</span><span class="o">&gt;</span> <span class="n">point_t</span><span class="p">;</span>
    204. 

  204. 

  205.   <span class="n">any_image</span><span class="p">();</span>
    206. 

  206.   <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">explicit</span> <span class="n">any_image</span><span class="p">(</span><span class="k">const</span> <span class="n">T</span><span class="o">&amp;</span> <span class="n">obj</span><span class="p">);</span>
    207. 

  207.   <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">explicit</span> <span class="n">any_image</span><span class="p">(</span><span class="n">T</span><span class="o">&amp;</span> <span class="n">obj</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">do_swap</span><span class="p">);</span>
    208. 

  208.   <span class="n">any_image</span><span class="p">(</span><span class="k">const</span> <span class="n">any_image</span><span class="o">&amp;</span> <span class="n">v</span><span class="p">);</span>
    209. 

  209. 

  210.   <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="n">any_image</span><span class="o">&amp;</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span><span class="k">const</span> <span class="n">T</span><span class="o">&amp;</span> <span class="n">obj</span><span class="p">);</span>
    211. 

  211.   <span class="n">any_image</span><span class="o">&amp;</span>                       <span class="k">operator</span><span class="o">=</span><span class="p">(</span><span class="k">const</span> <span class="n">any_image</span><span class="o">&amp;</span> <span class="n">v</span><span class="p">);</span>
    212. 

  212. 

  213.   <span class="kt">void</span> <span class="nf">recreate</span><span class="p">(</span><span class="k">const</span> <span class="n">point_t</span><span class="o">&amp;</span> <span class="n">dims</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">alignment</span><span class="o">=</span><span class="mi">1</span><span class="p">);</span>
    214. 

  214.   <span class="kt">void</span> <span class="nf">recreate</span><span class="p">(</span><span class="n">x_coord_t</span> <span class="n">width</span><span class="p">,</span> <span class="n">y_coord_t</span> <span class="n">height</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">alignment</span><span class="o">=</span><span class="mi">1</span><span class="p">);</span>
    215. 

  215. 

  216.   <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">num_channels</span><span class="p">()</span>  <span class="k">const</span><span class="p">;</span>
    217. 

  217.   <span class="n">point_t</span>     <span class="nf">dimensions</span><span class="p">()</span>    <span class="k">const</span><span class="p">;</span>
    218. 

  218.   <span class="n">x_coord_t</span>   <span class="nf">width</span><span class="p">()</span>         <span class="k">const</span><span class="p">;</span>
    219. 

  219.   <span class="n">y_coord_t</span>   <span class="nf">height</span><span class="p">()</span>        <span class="k">const</span><span class="p">;</span>
    220. 

  220. <span class="p">};</span>
    221. 

  221. </pre></div>
    222. 

  222. </div>
    223. 

  223. <p>Operations are invoked on variants via <code class="docutils literal"><span class="pre">apply_operation</span></code> passing a
    224. 

  224. function object to perform the operation. The code for every allowed
    225. 

  225. type in the variant is instantiated and the appropriate instantiation
    226. 

  226. is selected via a switch statement. Since image view algorithms
    227. 

  227. typically have time complexity at least linear on the number of
    228. 

  228. pixels, the single switch statement of image view variant adds
    229. 

  229. practically no measurable performance overhead compared to templated
    230. 

  230. image views.</p>
    231. 

  231. <p>Variants behave like the underlying type. Their copy constructor will
    232. 

  232. invoke the copy constructor of the underlying instance. Equality
    233. 

  233. operator will check if the two instances are of the same type and then
    234. 

  234. invoke their <code class="docutils literal"><span class="pre">operator==</span></code>, etc. The default constructor of a variant
    235. 

  235. will default-construct the first type. That means that
    236. 

  236. <code class="docutils literal"><span class="pre">any_image_view</span></code> has shallow default-constructor, copy-constructor,
    237. 

  237. assignment and equality comparison, whereas <code class="docutils literal"><span class="pre">any_image</span></code> has deep
    238. 

  238. ones.</p>
    239. 

  239. <p>It is important to note that even though <code class="docutils literal"><span class="pre">any_image_view</span></code> and
    240. 

  240. <code class="docutils literal"><span class="pre">any_image</span></code> resemble the static <code class="docutils literal"><span class="pre">image_view</span></code> and <code class="docutils literal"><span class="pre">image</span></code>, they
    241. 

  241. do not model the full requirements of <code class="docutils literal"><span class="pre">ImageViewConcept</span></code> and
    242. 

  242. <code class="docutils literal"><span class="pre">ImageConcept</span></code>. In particular they don&#8217;t provide access to the
    243. 

  243. pixels. There is no &#8220;any_pixel&#8221; or &#8220;any_pixel_iterator&#8221; in GIL. Such
    244. 

  244. constructs could be provided via the <code class="docutils literal"><span class="pre">variant</span></code> mechanism, but doing
    245. 

  245. so would result in inefficient algorithms, since the type resolution
    246. 

  246. would have to be performed per pixel. Image-level algorithms should be
    247. 

  247. implemented via <code class="docutils literal"><span class="pre">apply_operation</span></code>. That said, many common operations
    248. 

  248. are shared between the static and dynamic types. In addition, all of
    249. 

  249. the image view transformations and many STL-like image view algorithms
    250. 

  250. have overloads operating on <code class="docutils literal"><span class="pre">any_image_view</span></code>, as illustrated with
    251. 

  251. <code class="docutils literal"><span class="pre">copy_pixels</span></code>:</p>
    252. 

  252. <div class="highlight-cpp"><div class="highlight"><pre><span class="n">rgb8_view_t</span> <span class="nf">v1</span><span class="p">(...);</span>  <span class="c1">// concrete image view</span>
    253. 

  253. <span class="n">bgr8_view_t</span> <span class="nf">v2</span><span class="p">(...);</span>  <span class="c1">// concrete image view compatible with v1 and of the same size</span>
    254. 

  254. <span class="n">any_image_view</span><span class="o">&lt;</span><span class="n">Types</span><span class="o">&gt;</span>  <span class="n">av</span><span class="p">(...);</span>  <span class="c1">// run-time specified image view</span>
    255. 

  255. 

  256. <span class="c1">// Copies the pixels from v1 into v2.</span>
    257. 

  257. <span class="c1">// If the pixels are incompatible triggers compile error</span>
    258. 

  258. <span class="n">copy_pixels</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span><span class="n">v2</span><span class="p">);</span>
    259. 

  259. 

  260. <span class="c1">// The source or destination (or both) may be run-time instantiated.</span>
    261. 

  261. <span class="c1">// If they happen to be incompatible, throws std::bad_cast</span>
    262. 

  262. <span class="n">copy_pixels</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span> <span class="n">av</span><span class="p">);</span>
    263. 

  263. <span class="n">copy_pixels</span><span class="p">(</span><span class="n">av</span><span class="p">,</span> <span class="n">v2</span><span class="p">);</span>
    264. 

  264. <span class="n">copy_pixels</span><span class="p">(</span><span class="n">av</span><span class="p">,</span> <span class="n">av</span><span class="p">);</span>
    265. 

  265. </pre></div>
    266. 

  266. </div>
    267. 

  267. <p>By having algorithm overloads supporting dynamic constructs, we create
    268. 

  268. a base upon which it is possible to write algorithms that can work
    269. 

  269. with either compile-time or runtime images or views. The following
    270. 

  270. code, for example, uses the GIL I/O extension to turn an image on disk
    271. 

  271. upside down:</p>
    272. 

  272. <div class="highlight-cpp"><div class="highlight"><pre><span class="cp">#include</span> <span class="cpf">&lt;boost\gil\extension\io\jpeg_dynamic_io.hpp&gt;</span><span class="cp"></span>
    273. 

  273. 

  274. <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">Image</span><span class="o">&gt;</span>    <span class="c1">// Could be rgb8_image_t or any_image&lt;...&gt;</span>
    275. 

  275. <span class="kt">void</span> <span class="n">save_180rot</span><span class="p">(</span><span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">&amp;</span> <span class="n">file_name</span><span class="p">)</span>
    276. 

  276. <span class="p">{</span>
    277. 

  277.   <span class="n">Image</span> <span class="n">img</span><span class="p">;</span>
    278. 

  278.   <span class="n">jpeg_read_image</span><span class="p">(</span><span class="n">file_name</span><span class="p">,</span> <span class="n">img</span><span class="p">);</span>
    279. 

  279.   <span class="n">jpeg_write_view</span><span class="p">(</span><span class="n">file_name</span><span class="p">,</span> <span class="n">rotated180_view</span><span class="p">(</span><span class="n">view</span><span class="p">(</span><span class="n">img</span><span class="p">)));</span>
    280. 

  280. <span class="p">}</span>
    281. 

  281. </pre></div>
    282. 

  282. </div>
    283. 

  283. <p>It can be instantiated with either a compile-time or a runtime image
    284. 

  284. because all functions it uses have overloads taking runtime
    285. 

  285. constructs. For example, here is how <code class="docutils literal"><span class="pre">rotated180_view</span></code> is
    286. 

  286. implemented:</p>
    287. 

  287. <div class="highlight-cpp"><div class="highlight"><pre><span class="c1">// implementation using templated view</span>
    288. 

  288. <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span>
    289. 

  289. <span class="k">typename</span> <span class="n">dynamic_xy_step_type</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">type</span> <span class="n">rotated180_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> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
    290. 

  290. 

  291. <span class="k">namespace</span> <span class="n">detail</span>
    292. 

  292. <span class="p">{</span>
    293. 

  293.   <span class="c1">// the function, wrapped inside a function object</span>
    294. 

  294.   <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">Result</span><span class="o">&gt;</span> <span class="k">struct</span> <span class="n">rotated180_view_fn</span>
    295. 

  295.   <span class="p">{</span>
    296. 

  296.       <span class="k">typedef</span> <span class="n">Result</span> <span class="n">result_type</span><span class="p">;</span>
    297. 

  297.       <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span> <span class="n">result_type</span> <span class="k">operator</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> <span class="k">const</span>
    298. 

  298. <span class="p">{</span>
    299. 

  299.           <span class="k">return</span> <span class="n">result_type</span><span class="p">(</span><span class="n">rotated180_view</span><span class="p">(</span><span class="n">src</span><span class="p">));</span>
    300. 

  300.       <span class="p">}</span>
    301. 

  301.   <span class="p">};</span>
    302. 

  302. <span class="p">}</span>
    303. 

  303. 

  304. <span class="c1">// overloading of the function using variant. Takes and returns run-time bound view.</span>
    305. 

  305. <span class="c1">// The returned view has a dynamic step</span>
    306. 

  306. <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">ViewTypes</span><span class="o">&gt;</span> <span class="kr">inline</span> <span class="c1">// Models MPL Random Access Container of models of ImageViewConcept</span>
    307. 

  307. <span class="k">typename</span> <span class="n">dynamic_xy_step_type</span><span class="o">&lt;</span><span class="n">any_image_view</span><span class="o">&lt;</span><span class="n">ViewTypes</span><span class="o">&gt;</span> <span class="o">&gt;::</span><span class="n">type</span> <span class="n">rotated180_view</span><span class="p">(</span><span class="k">const</span> <span class="n">any_image_view</span><span class="o">&lt;</span><span class="n">ViewTypes</span><span class="o">&gt;&amp;</span> <span class="n">src</span><span class="p">)</span>
    308. 

  308. <span class="p">{</span>
    309. 

  309.   <span class="k">return</span> <span class="n">apply_operation</span><span class="p">(</span><span class="n">src</span><span class="p">,</span><span class="n">detail</span><span class="o">::</span><span class="n">rotated180_view_fn</span><span class="o">&lt;</span><span class="k">typename</span> <span class="n">dynamic_xy_step_type</span><span class="o">&lt;</span><span class="n">any_image_view</span><span class="o">&lt;</span><span class="n">ViewTypes</span><span class="o">&gt;</span> <span class="o">&gt;::</span><span class="n">type</span><span class="o">&gt;</span><span class="p">());</span>
    310. 

  310. <span class="p">}</span>
    311. 

  311. </pre></div>
    312. 

  312. </div>
    313. 

  313. <p>Variants should be used with caution (especially algorithms that take
    314. 

  314. more than one variant) because they instantiate the algorithm for
    315. 

  315. every possible model that the variant can take. This can take a toll
    316. 

  316. on compile time and executable size. Despite these limitations,
    317. 

  317. <code class="docutils literal"><span class="pre">variant</span></code> is a powerful technique that allows us to combine the
    318. 

  318. speed of compile-time resolution with the flexibility of run-time
    319. 

  319. resolution. It allows us to treat images of different parameters
    320. 

  320. uniformly as a collection and store them in the same container.</p>
    321. 

  321. </div>
    322. 

  322. 

  323. 

  324.     <div class="navbar" style="text-align:right;">
    325. 

  325.       
    326. 

  326.       
    327. 

  327.       <a class="prev" title="Image" href="image.html"><img src="../_static/prev.png" alt="prev"/></a>
    328. 

  328.       <a class="up" title="Design Guide" href="index.html"><img src="../_static/up.png" alt="up"/></a>
    329. 

  329.       <a class="next" title="Metafunctions" href="metafunctions.html"><img src="../_static/next.png" alt="next"/></a>
    330. 

  330.       
    331. 

  331.     </div>
    332. 

  332.     </div>
    333. 

  333.     <div class="footer" role="contentinfo">
    334. 

  334.       Last updated on 2019-12-10 00:12:10.
    335. 

  335.       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
    336. 

  336.     </div>
    337. 

  337.   </body>
    338. 

  338. </html>
    339.