image_view.hpp

//
// Copyright 2005-2007 Adobe Systems Incorporated
//
// Distributed under the Boost Software License, Version 1.0
// See accompanying file LICENSE_1_0.txt or copy at
// http://www.boost.org/LICENSE_1_0.txt
//
#ifndef BOOST_GIL_IMAGE_VIEW_HPP
#define BOOST_GIL_IMAGE_VIEW_HPP

#include <boost/gil/dynamic_step.hpp>
#include <boost/gil/iterator_from_2d.hpp>

#include <boost/assert.hpp>

#include <cstddef>
#include <iterator>

namespace boost { namespace gil {

template <typename Loc>     // Models 2D Pixel Locator
class image_view
{
public:
    // aliases required by ConstRandomAccessNDImageViewConcept
    static const std::size_t num_dimensions=2;
    using value_type = typename Loc::value_type;
    using reference = typename Loc::reference;       // result of dereferencing
    using coord_t = typename Loc::coord_t;      // 1D difference type (same for all dimensions)
    using difference_type = coord_t; // result of operator-(1d_iterator,1d_iterator)
    using point_t = typename Loc::point_t;
    using locator = Loc;
    using const_t = image_view<typename Loc::const_t>;      // same as this type, but over const values
    template <std::size_t D> struct axis
    {
        using coord_t = typename Loc::template axis<D>::coord_t; // difference_type along each dimension
        using iterator = typename Loc::template axis<D>::iterator; // 1D iterator type along each dimension
    };
    using iterator = iterator_from_2d<Loc>;       // 1D iterator type for each pixel left-to-right inside top-to-bottom
    using const_iterator = typename const_t::iterator;  // may be used to examine, but not to modify values
    using const_reference = typename const_t::reference; // behaves as a const reference
    using pointer = typename std::iterator_traits<iterator>::pointer; // behaves as a pointer to the value type
    using reverse_iterator = std::reverse_iterator<iterator>;
    using size_type = std::size_t;

    // aliases required by ConstRandomAccess2DImageViewConcept
    using xy_locator = locator;
    using x_iterator = typename xy_locator::x_iterator;     // pixel iterator along a row
    using y_iterator = typename xy_locator::y_iterator;     // pixel iterator along a column
    using x_coord_t = typename xy_locator::x_coord_t;
    using y_coord_t = typename xy_locator::y_coord_t;

    template <typename Deref>
    struct add_deref
    {
        using type = image_view<typename Loc::template add_deref<Deref>::type>;
        static type make(image_view<Loc> const& view, Deref const& d)
        {
            return type(view.dimensions(), Loc::template add_deref<Deref>::make(view.pixels(), d));
        }
    };

    image_view() : _dimensions(0,0) {}
    image_view(image_view const& img_view)
        : _dimensions(img_view.dimensions()), _pixels(img_view.pixels())
    {}

    template <typename View>
    image_view(View const& view) : _dimensions(view.dimensions()), _pixels(view.pixels()) {}

    template <typename L2>
    image_view(point_t const& dims, L2 const& loc) : _dimensions(dims), _pixels(loc) {}

    template <typename L2>
    image_view(coord_t width, coord_t height, L2 const& loc)
        : _dimensions(x_coord_t(width), y_coord_t(height)), _pixels(loc)
    {}

    template <typename View>
    image_view& operator=(View const& view)
    {
        _pixels = view.pixels();
        _dimensions = view.dimensions();
        return *this;
    }

    image_view& operator=(image_view const& view)
    {
        // TODO: Self-assignment protection?
        _pixels = view.pixels();
        _dimensions = view.dimensions();
        return *this;
    }

    template <typename View>
    bool operator==(View const &view) const
    {
        return pixels() == view.pixels() && dimensions() == view.dimensions();
    }

    template <typename View>
    bool operator!=(View const& view) const
    {
        return !(*this == view);
    }

    template <typename L2>
    friend void swap(image_view<L2> &lhs, image_view<L2> &rhs);

    void swap(image_view<Loc>& other)
    {
        using boost::gil::swap;
        swap(*this, other);
    }

    auto dimensions() const -> point_t const&
    {
        return _dimensions;
    }

    auto pixels() const -> locator const&
    {
        return _pixels;
    }

    auto width() const -> x_coord_t
    {
        return dimensions().x;
    }

    auto height() const -> y_coord_t
    {
        return dimensions().y;
    }

    auto num_channels() const -> std::size_t
    {
        return gil::num_channels<value_type>::value;
    }

    bool is_1d_traversable() const
    {
        return _pixels.is_1d_traversable(width());
    }

    bool empty() const
    {
        return !(width() > 0 && height() > 0);
    }

    auto front() const -> reference
    {
        BOOST_ASSERT(!empty());
        return *begin();
    }

    auto back() const -> reference
    {
        BOOST_ASSERT(!empty());
        return *rbegin();
    }

    //\{@
    auto size() const -> size_type
    {
        return width() * height();
    }

    auto begin() const -> iterator
    {
        return iterator(_pixels, _dimensions.x);
    }

    auto end() const -> iterator
    {
        // potential performance problem!
        return begin() + static_cast<difference_type>(size());
    }

    auto rbegin() const -> reverse_iterator
    {
        return reverse_iterator(end());
    }

    auto rend() const -> reverse_iterator
    {
        return reverse_iterator(begin());
    }

    auto operator[](difference_type i) const -> reference
    {
        BOOST_ASSERT(i < static_cast<difference_type>(size()));
        return begin()[i]; // potential performance problem!
    }

    auto at(difference_type i) const -> iterator
    {
        // UB if the specified increment advances non-incrementable iterator (i.e. past-the-end)
        BOOST_ASSERT(i < static_cast<difference_type>(size()));
        return begin() + i;
    }

    auto at(point_t const& p) const -> iterator
    {
        // UB if the specified coordinates advance non-incrementable iterator (i.e. past-the-end)
        BOOST_ASSERT(0 <= p.x && p.x < width());
        BOOST_ASSERT(0 <= p.y && p.y < height());
        return begin() + p.y * width() + p.x;
    }

    auto at(x_coord_t x, y_coord_t y) const -> iterator
    {
        // UB if the specified coordinates advance non-incrementable iterator (i.e. past-the-end)
        BOOST_ASSERT(0 <= x && x < width());
        BOOST_ASSERT(0 <= y && y < height());
        return begin() + y * width() + x;
    }
    //\}@

    //\{@
    auto operator()(point_t const& p) const -> reference
    {
        BOOST_ASSERT(0 <= p.x && p.x < width());
        BOOST_ASSERT(0 <= p.y && p.y < height());
        return _pixels(p.x, p.y);
    }

    auto operator()(x_coord_t x, y_coord_t y) const -> reference
    {
        BOOST_ASSERT(0 <= x && x < width());
        BOOST_ASSERT(0 <= y && y < height());
        return _pixels(x, y);
    }

    template <std::size_t D>
    auto axis_iterator(point_t const& p) const -> typename axis<D>::iterator
    {
        // Allow request for iterators from inclusive range of [begin, end]
        BOOST_ASSERT(0 <= p.x && p.x <= width());
        BOOST_ASSERT(0 <= p.y && p.y <= height());
        return _pixels.template axis_iterator<D>(p);
    }

    auto xy_at(x_coord_t x, y_coord_t y) const -> xy_locator
    {
        // TODO: Are relative locations of neighbors with negative offsets valid? Sampling?
        BOOST_ASSERT(x < width());
        BOOST_ASSERT(y <= height());
        return _pixels + point_t(x, y);
    }

    auto xy_at(point_t const& p) const -> xy_locator
    {
        // TODO: Are relative locations of neighbors with negative offsets valid? Sampling?
        BOOST_ASSERT(p.x < width());
        BOOST_ASSERT(p.y < height());
        return _pixels + p;
    }
    //\}@

    //\{@
    auto x_at(x_coord_t x, y_coord_t y) const -> x_iterator
    {
        BOOST_ASSERT(0 <= x && x <= width()); // allow request for [begin, end] inclusive
        BOOST_ASSERT(0 <= y && y < height()); // TODO: For empty image/view, shouldn't we accept: row_begin(0) == view.row_end(0) ?
        return _pixels.x_at(x, y);
    }

    auto x_at(point_t const& p) const -> x_iterator
    {
        BOOST_ASSERT(0 <= p.x && p.x <= width()); // allow request for [begin, end] inclusive
        BOOST_ASSERT(0 <= p.y && p.y < height()); // TODO: For empty image/view, shouldn't we accept: row_begin(0) == view.row_end(0) ?
        return _pixels.x_at(p);
    }

    auto row_begin(y_coord_t y) const -> x_iterator
    {
        BOOST_ASSERT(0 <= y && y < height());
        return x_at(0, y);
    }

    auto row_end(y_coord_t y) const -> x_iterator
    {
        BOOST_ASSERT(0 <= y && y < height());
        return x_at(width(), y);
    }
    //\}@

    //\{@
    auto y_at(x_coord_t x, y_coord_t y) const -> y_iterator
    {
        BOOST_ASSERT(0 <= x && x < width()); // TODO: For empty image/view, shouldn't we accept: view.col_begin(0) == view.col_end(0) ?
        BOOST_ASSERT(0 <= y && y <= height()); // allow request for [begin, end] inclusive
        return xy_at(x, y).y();
    }

    auto y_at(point_t const& p) const -> y_iterator
    {
        BOOST_ASSERT(0 <= p.x && p.x < width()); // TODO: For empty image/view, shouldn't we accept: view.col_begin(0) == view.col_end(0) ?
        BOOST_ASSERT(0 <= p.y && p.y <= height()); // allow request for [begin, end] inclusive
        return xy_at(p).y();
    }

    auto col_begin(x_coord_t x) const -> y_iterator
    {
        BOOST_ASSERT(0 <= x && x < width());
        return y_at(x, 0);
    }

    auto col_end(x_coord_t x) const -> y_iterator
    {
        BOOST_ASSERT(0 <= x && x < width());
        return y_at(x, height());
    }
    //\}@

private:
    template <typename L2>
    friend class image_view;

    point_t    _dimensions;
    xy_locator _pixels;
};

template <typename L2>
inline void swap(image_view<L2>& x, image_view<L2>& y) {
    using std::swap;
    swap(x._dimensions,y._dimensions);
    swap(x._pixels, y._pixels);            // TODO: Extend further
}

//  PixelBasedConcept

template <typename L>
struct channel_type<image_view<L> > : public channel_type<L> {};

template <typename L>
struct color_space_type<image_view<L> > : public color_space_type<L> {};

template <typename L>
struct channel_mapping_type<image_view<L> > : public channel_mapping_type<L> {};

template <typename L>
struct is_planar<image_view<L> > : public is_planar<L> {};

//  HasDynamicXStepTypeConcept

template <typename L>
struct dynamic_x_step_type<image_view<L>>
{
    using type = image_view<typename gil::dynamic_x_step_type<L>::type>;
};

//  HasDynamicYStepTypeConcept

template <typename L>
struct dynamic_y_step_type<image_view<L>>
{
    using type = image_view<typename gil::dynamic_y_step_type<L>::type>;
};

//  HasTransposedTypeConcept

template <typename L>
struct transposed_type<image_view<L>>
{
    using type = image_view<typename transposed_type<L>::type>;
};

}}  // namespace boost::gil

#endif