gil/io/io.hpp

0001 //
0002 // Copyright 2007-2008 Christian Henning, Andreas Pokorny
0003 //
0004 // Distributed under the Boost Software License, Version 1.0
0005 // See accompanying file LICENSE_1_0.txt or copy at
0006 // http://www.boost.org/LICENSE_1_0.txt
0007 //
0008 #ifndef BOOST_GIL_IO_IO_HPP
0009 #define BOOST_GIL_IO_IO_HPP
0010
0011 /*!
0012  * \page iobackend Adding a new io backend
0013  * \section Overview of backend requirements
0014  * To add support for a new IO backend the following is required:
0015  *  - a format tag, to identify the image format, derived from boost::gil::format_tag
0016  *  - boolean meta function is_supported<PixelType,FormatTag> must be implemented for
0017  *    the new format tag
0018  *  - explicit specialisation of image_read_info<FormatTag> must be provided, containing
0019  *    runtime information available before/at reading the image
0020  *  - explicit specialisation of image_write_info<FormatTag> must be provided, containing
0021  *    runtime encoding parameters for writing an image
0022  *  - An image reader must be specialized:
0023  *    \code
0024  *      template<typename IODevice, typename ConversionPolicy>
0025  *      struct boost::gil::reader<IODevice,FormatTag,ConversionPolicy>
0026  *      {
0027  *        reader( IODevice & device )
0028  *        reader( IODevice & device, typename ConversionPolicy::color_converter_type const& cc )
0029  *        image_read_info<FormatTag> get_info();
0030  *        template<typename Image>
0031  *        void read_image( Image &, point_t const& top_left );
0032  *        template<typename View>
0033  *        void read_view( View &, point_t const& top_left );
0034  *      };
0035  *    \endcode
0036  *  - An image writer must be specialized:
0037  *    \code
0038  *      \template <typename IODevice>
0039  *      struct boost::gil::writer<IODevice,FormatTag>
0040  *      {
0041  *        writer( IODevice & device )
0042  *        template<typename View>
0043  *        void apply( View const&, point_t const& top_left );
0044  *        template<typename View>
0045  *        void apply( View const&, point_t const& top_left, image_write_info<FormatTag> const& );
0046  *      };
0047  *    \endcode
0048  *
0049  * Or instead of the items above implement overloads of read_view, read_and_convert_view, read_image,
0050  * read_and_convert_image, write_view and read_image_info.
0051  *
0052  * \section ConversionPolicy Interface of the ConversionPolicy
0053  * There are two different conversion policies in use, when reading images:
0054  * read_and_convert<ColorConverter> and read_and_no_convert. ColorConverter
0055  * can be a user defined color converter.
0056  *
0057  * \code
0058  * struct ConversionPolicy
0059  * {
0060  *    template<typename InputIterator,typename OutputIterator>
0061  *    void read( InputIterator in_begin, InputIterator in_end,
0062  *          OutputIterator out_end );
0063  * };
0064  * \endcode
0065  *
0066  * Methods like read_view and read_image are supposed to bail out with an
0067  * exception instead of converting the image
0068  *
0069  * \section IODevice Concept of IO Device
0070  * A Device is simply an object used to read and write data to and from a stream.
0071  * The IODevice was added as a template paramter to be able to replace the file_name
0072  * access functionality. This is only an interim solution, as soon as boost provides
0073  * a good IO library, interfaces/constraints provided by that library could be used.
0074  *
0075  * \code
0076  *  concept IODevice
0077  *  {
0078  *      void IODevice::read( unsigned char* data, int count );
0079  *      void IODevice::write( unsigned char* data, int count );
0080  *      void IODevice::seek(long count, int whence);
0081  *      void IODevice::flush();
0082  *  };
0083  * \endcode
0084  *
0085  * For the time being a boolean meta function must be specialized:
0086  * \code
0087  * namespace boost{namespace gil{namespace detail{
0088  *  template<typename Device>
0089  *  struct detail::is_input_device;
0090  * }}}
0091  * \endcode
0092  *
0093  */
0094
0095 #endif