pixel_2d_locator_base Class Template Reference
[Models, Models]

#include <locator.hpp>

Inheritance diagram for pixel_2d_locator_base:

List of all members.

---

Detailed Description

template<typename Loc, typename XIterator, typename YIterator>
class boost::gil::pixel_2d_locator_base< Loc, XIterator, YIterator >

base class for models of PixelLocatorConcept

Pixel locator is similar to a pixel iterator, but allows for 2D navigation of pixels within an image view. It has a 2D difference_type and supports random access operations like:

     difference_type offset2(2,3);
     locator+=offset2;
     locator[offset2]=my_pixel;

In addition, each coordinate acts as a random-access iterator that can be modified separately: "++locator.x()" or "locator.y()+=10" thereby moving the locator horizontally or vertically.

It is called a locator because it doesn't implement the complete interface of a random access iterator. For example, increment and decrement operations don't make sense (no way to specify dimension). Also 2D difference between two locators cannot be computed without knowledge of the X position within the image.

This base class provides most of the methods and typedefs needed to create a model of a locator. GIL provides two locator models as subclasses of pixel_2d_locator_base. A memory-based locator, memory_based_2d_locator and a virtual locator, virtual_2d_locator. The minimum functionality a subclass must provide is this:

 class my_locator : public pixel_2d_locator_base<my_locator, ..., ...> {  // supply the types for x-iterator and y-iterator
        typedef ... const_t;                      // read-only locator

        template <typename Deref> struct add_deref {
            typedef ... type;                     // locator that invokes the Deref dereference object upon pixel access
            static type make(const my_locator& loc, const Deref& d);
        };

        my_locator();
        my_locator(const my_locator& pl);

        // constructors with dynamic step in y (and x). Only valid for locators with dynamic steps
        my_locator(const my_locator& loc, coord_t y_step);
        my_locator(const my_locator& loc, coord_t x_step, coord_t y_step, bool transpose);

        bool              operator==(const my_locator& p) const;

        // return _references_ to horizontal/vertical iterators. Advancing them moves this locator
        x_iterator&       x();
        y_iterator&       y();
        x_iterator const& x() const;
        y_iterator const& y() const;

        // return the vertical distance to another locator. Some models need the horizontal distance to compute it
        y_coord_t         y_distance_to(const my_locator& loc2, x_coord_t xDiff) const;

        // return true iff incrementing an x-iterator located at the last column will position it at the first 
        // column of the next row. Some models need the image width to determine that.
        bool              is_1d_traversable(x_coord_t width) const;
 };

Models may choose to override some of the functions in the base class with more efficient versions.

Public Types
typedef XIterator	x_iterator
typedef YIterator	y_iterator
typedef std::iterator_traits < x_iterator >::value_type	value_type
typedef std::iterator_traits < x_iterator >::reference	reference
typedef std::iterator_traits < x_iterator > ::difference_type	coord_t
typedef point2< coord_t >	difference_type
typedef difference_type	point_t
typedef point_t::template axis < 0 >::coord_t	x_coord_t
typedef point_t::template axis < 1 >::coord_t	y_coord_t
typedef difference_type	cached_location_t
Public Member Functions
bool	operator!= (const Loc &p) const
x_iterator	x_at (x_coord_t dx, y_coord_t dy) const
x_iterator	x_at (const difference_type &d) const
y_iterator	y_at (x_coord_t dx, y_coord_t dy) const
y_iterator	y_at (const difference_type &d) const
Loc	xy_at (x_coord_t dx, y_coord_t dy) const
Loc	xy_at (const difference_type &d) const
template<std::size_t D>
axis< D >::iterator &	axis_iterator ()
template<std::size_t D>
axis< D >::iterator const &	axis_iterator () const
template<std::size_t D>
axis< D >::iterator	axis_iterator (const point_t &p) const
reference	operator() (x_coord_t dx, y_coord_t dy) const
reference	operator[] (const difference_type &d) const
reference	operator* () const
Loc &	operator+= (const difference_type &d)
Loc &	operator-= (const difference_type &d)
Loc	operator+ (const difference_type &d) const
Loc	operator- (const difference_type &d) const
cached_location_t	cache_location (const difference_type &d) const
cached_location_t	cache_location (x_coord_t dx, y_coord_t dy) const
Static Public Attributes
static const std::size_t	num_dimensions = 2
Friends
class	pixel_2d_locator

---

The documentation for this class was generated from the following file:

• locator.hpp