libs/gil/doc/html/reference/iobackend.html

   1 <!-- HTML header for doxygen 1.8.13-->
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <head>
   5     <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
   6     <meta http-equiv="X-UA-Compatible" content="IE=9"/>
   7     <meta name="generator" content="Doxygen 1.8.15"/>
   8     <meta name="viewport" content="width=device-width, initial-scale=1"/>
   9     <title>Generic Image Library: Adding a new io backend</title>
  10     <link href="tabs.css" rel="stylesheet" type="text/css"/>
  11     <script type="text/javascript" src="jquery.js"></script>
  12     <script type="text/javascript" src="dynsections.js"></script>
  13     <link href="doxygen.css" rel="stylesheet" type="text/css" />
  14     <link href="doxygen-boost.css" rel="stylesheet" type="text/css"/>
  15   </head>
  16   <body>
  17     <div class="boost-header">
  18       <table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
  19         <tr>
  20           <td valign="top" width="300">
  21             <h3><a href="../index.html"><img alt="Boost GIL" src="../_static/gil.png" border="0"></a></h3>
  22           </td>
  23           <td ><h1 align="center"><a href="../index.html"></a></h1></td>
  24           <td></td>
  25         </tr>
  26       </table>
  27     </div>
  28     <hr/>
  29     <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
  30 <!-- Generated by Doxygen 1.8.15 -->
  31 <script type="text/javascript" src="menudata.js"></script>
  32 <script type="text/javascript" src="menu.js"></script>
  33 <script type="text/javascript">
  34 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
  35 $(function() {
  36   initMenu('',false,false,'search.php','Search');
  37 });
  38 /* @license-end */</script>
  39 <div id="main-nav"></div>
  40 </div><!-- top -->
  41 <div class="PageDoc"><div class="header">
  42   <div class="headertitle">
  43 <div class="title">Adding a new io backend </div>  </div>
  44 </div><!--header-->
  45 <div class="contents">
  46 <div class="textblock"><h1><a class="anchor" id="Overview"></a>
  47 of backend requirements</h1>
  48 <p>To add support for a new IO backend the following is required:</p><ul>
  49 <li>a format tag, to identify the image format, derived from boost::gil::format_tag</li>
  50 <li>boolean meta function is_supported&lt;PixelType,FormatTag&gt; must be implemented for the new format tag</li>
  51 <li>explicit specialisation of image_read_info&lt;FormatTag&gt; must be provided, containing runtime information available before/at reading the image</li>
  52 <li>explicit specialisation of image_write_info&lt;FormatTag&gt; must be provided, containing runtime encoding parameters for writing an image</li>
  53 <li>An image reader must be specialized: <div class="fragment"><div class="line"><span class="keyword">template</span>&lt;<span class="keyword">typename</span> IODevice, <span class="keyword">typename</span> ConversionPolicy&gt;</div><div class="line"><span class="keyword">struct </span>boost::gil::reader&lt;IODevice,FormatTag,ConversionPolicy&gt;</div><div class="line">{</div><div class="line">  reader( IODevice &amp; device )</div><div class="line">  reader( IODevice &amp; device, <span class="keyword">typename</span> ConversionPolicy::color_converter_type <span class="keyword">const</span>&amp; cc )</div><div class="line">  image_read_info&lt;FormatTag&gt; get_info();</div><div class="line">  <span class="keyword">template</span>&lt;<span class="keyword">typename</span> Image&gt;</div><div class="line">  <span class="keywordtype">void</span> <a class="code" href="group___i_o.html#gac1e65b2ad8cd28fe8d694f1663df0d78">read_image</a>( Image &amp;, point_t <span class="keyword">const</span>&amp; top_left );</div><div class="line">  <span class="keyword">template</span>&lt;<span class="keyword">typename</span> View&gt;</div><div class="line">  <span class="keywordtype">void</span> <a class="code" href="group___i_o.html#ga9b5ae3d12c73aa1d81245fd5f8772847">read_view</a>( View &amp;, point_t <span class="keyword">const</span>&amp; top_left );</div><div class="line">};</div></div><!-- fragment --></li>
  54 <li>An image writer must be specialized: <div class="fragment"><div class="line">\template &lt;typename IODevice&gt;</div><div class="line"><span class="keyword">struct </span>boost::gil::writer&lt;IODevice,FormatTag&gt;</div><div class="line">{</div><div class="line">  writer( IODevice &amp; device )</div><div class="line">  <span class="keyword">template</span>&lt;<span class="keyword">typename</span> View&gt;</div><div class="line">  <span class="keywordtype">void</span> apply( View <span class="keyword">const</span>&amp;, point_t <span class="keyword">const</span>&amp; top_left );</div><div class="line">  <span class="keyword">template</span>&lt;<span class="keyword">typename</span> View&gt;</div><div class="line">  <span class="keywordtype">void</span> apply( View <span class="keyword">const</span>&amp;, point_t <span class="keyword">const</span>&amp; top_left, image_write_info&lt;FormatTag&gt; <span class="keyword">const</span>&amp; );</div><div class="line">};</div></div><!-- fragment --></li>
  55 </ul>
  56 <p>Or instead of the items above implement overloads of read_view, read_and_convert_view, read_image, read_and_convert_image, write_view and read_image_info.</p>
  57 <h1><a class="anchor" id="ConversionPolicy"></a>
  58 Interface of the ConversionPolicy</h1>
  59 <p>There are two different conversion policies in use, when reading images: read_and_convert&lt;ColorConverter&gt; and read_and_no_convert. ColorConverter can be a user defined color converter.</p>
  60 <div class="fragment"><div class="line"><span class="keyword">struct </span>ConversionPolicy</div><div class="line">{</div><div class="line">   <span class="keyword">template</span>&lt;<span class="keyword">typename</span> InputIterator,<span class="keyword">typename</span> OutputIterator&gt;</div><div class="line">   <span class="keywordtype">void</span> read( InputIterator in_begin, InputIterator in_end,</div><div class="line">         OutputIterator out_end );</div><div class="line">};</div></div><!-- fragment --><p>Methods like read_view and read_image are supposed to bail out with an exception instead of converting the image</p>
  61 <h1><a class="anchor" id="IODevice"></a>
  62 Concept of IO Device</h1>
  63 <p>A Device is simply an object used to read and write data to and from a stream. The IODevice was added as a template paramter to be able to replace the file_name access functionality. This is only an interim solution, as soon as boost provides a good IO library, interfaces/constraints provided by that library could be used.</p>
  64 <div class="fragment"><div class="line">concept IODevice</div><div class="line">{</div><div class="line">    <span class="keywordtype">void</span> IODevice::read( <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span>* data, <span class="keywordtype">int</span> count );</div><div class="line">    <span class="keywordtype">void</span> IODevice::write( <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span>* data, <span class="keywordtype">int</span> count );</div><div class="line">    <span class="keywordtype">void</span> IODevice::seek(<span class="keywordtype">long</span> count, <span class="keywordtype">int</span> whence);</div><div class="line">    <span class="keywordtype">void</span> IODevice::flush();</div><div class="line">};</div></div><!-- fragment --><p>For the time being a boolean meta function must be specialized: </p><div class="fragment"><div class="line"><span class="keyword">namespace </span>boost{<span class="keyword">namespace </span>gil{<span class="keyword">namespace </span>detail{</div><div class="line"> <span class="keyword">template</span>&lt;<span class="keyword">typename</span> Device&gt;</div><div class="line"> <span class="keyword">struct </span>detail::is_input_device;</div><div class="line">}}}</div></div><!-- fragment --> </div></div><!-- PageDoc -->
  65 </div><!-- contents -->
  66      <!-- HTML footer for doxygen 1.8.13-->
  67      <!-- start footer part -->
  68      <hr class="footer"/>
  69      <address class="footer">
  70       <small>
  71         Generated by &#160;<a href="http://www.doxygen.org/index.html">doxygen</a> 1.8.15
  72       </small>
  73     </address>
  74   </body>
  75 </html>