Metafunctions
Overview
Flexibility comes at a price. GIL types can be very long and hard to read. To address this problem, GIL provides typedefs to refer to any standard image, pixel iterator, pixel locator, pixel reference or pixel value.
They follow this pattern:
*ColorSpace* + *BitDepth* + ["s|f"] + ["c"] + ["_planar"] + ["_step"] + *ClassType* + "_t"
where ColorSpace also indicates the ordering of components.
Examples are rgb, bgr, cmyk, rgba. BitDepth can be, for
example, 8,``16``,``32``. By default the bits are unsigned integral type.
Append s to the bit depth to indicate signed integral, or f to
indicate floating point. c indicates object whose associated pixel
reference is immutable. _planar indicates planar organization (as opposed
to interleaved). _step indicates the type has a dynamic step and
ClassType is _image (image, using a standard allocator), _view
(image view), _loc (pixel locator), _ptr (pixel iterator), _ref
(pixel reference), _pixel (pixel value).
Here are examples:
bgr8_image_t i; // 8-bit unsigned (unsigned char) interleaved BGR image
cmyk16_pixel_t; x; // 16-bit unsigned (unsigned short) CMYK pixel value;
cmyk16sc_planar_ref_t p(x); // const reference to a 16-bit signed integral (signed short) planar CMYK pixel x.
rgb32f_planar_step_ptr_t ii; // step iterator to a floating point 32-bit (float) planar RGB pixel.
Homogeneous memory-based images
GIL provides the metafunctions that return the types of standard homogeneous memory-based GIL constructs given a channel type, a layout, and whether the construct is planar, has a step along the X direction, and is mutable:
template <typename ChannelValue, typename Layout, bool IsPlanar=false, bool IsMutable=true>
struct pixel_reference_type { typedef ... type; };
template <typename Channel, typename Layout>
struct pixel_value_type { typedef ... type; };
template <typename ChannelValue, typename Layout, bool IsPlanar=false, bool IsStep=false, bool IsMutable=true>
struct iterator_type { typedef ... type; };
template <typename ChannelValue, typename Layout, bool IsPlanar=false, bool IsXStep=false, bool IsMutable=true>
struct locator_type { typedef ... type; };
template <typename ChannelValue, typename Layout, bool IsPlanar=false, bool IsXStep=false, bool IsMutable=true>
struct view_type { typedef ... type; };
template <typename ChannelValue, typename Layout, bool IsPlanar=false, typename Alloc=std::allocator<unsigned char> >
struct image_type { typedef ... type; };
template <typename BitField, typename ChannelBitSizeVector, typename Layout, typename Alloc=std::allocator<unsigned char> >
struct packed_image_type { typedef ... type; };
template <typename ChannelBitSizeVector, typename Layout, typename Alloc=std::allocator<unsigned char> >
struct bit_aligned_image_type { typedef ... type; };
Packed and bit-aligned images
There are also helper metafunctions to construct packed and bit-aligned images with up to five channels:
template <typename BitField, unsigned Size1,
typename Layout, typename Alloc=std::allocator<unsigned char> >
struct packed_image1_type { typedef ... type; };
template <typename BitField, unsigned Size1, unsigned Size2,
typename Layout, typename Alloc=std::allocator<unsigned char> >
struct packed_image2_type { typedef ... type; };
template <typename BitField, unsigned Size1, unsigned Size2, unsigned Size3,
typename Layout, typename Alloc=std::allocator<unsigned char> >
struct packed_image3_type { typedef ... type; };
template <typename BitField, unsigned Size1, unsigned Size2, unsigned Size3, unsigned Size4,
typename Layout, typename Alloc=std::allocator<unsigned char> >
struct packed_image4_type { typedef ... type; };
template <typename BitField, unsigned Size1, unsigned Size2, unsigned Size3, unsigned Size4, unsigned Size5,
typename Layout, typename Alloc=std::allocator<unsigned char> >
struct packed_image5_type { typedef ... type; };
template <unsigned Size1,
typename Layout, typename Alloc=std::allocator<unsigned char> >
struct bit_aligned_image1_type { typedef ... type; };
template <unsigned Size1, unsigned Size2,
typename Layout, typename Alloc=std::allocator<unsigned char> >
struct bit_aligned_image2_type { typedef ... type; };
template <unsigned Size1, unsigned Size2, unsigned Size3,
typename Layout, typename Alloc=std::allocator<unsigned char> >
struct bit_aligned_image3_type { typedef ... type; };
template <unsigned Size1, unsigned Size2, unsigned Size3, unsigned Size4,
typename Layout, typename Alloc=std::allocator<unsigned char> >
struct bit_aligned_image4_type { typedef ... type; };
template <unsigned Size1, unsigned Size2, unsigned Size3, unsigned Size4, unsigned Size5,
typename Layout, typename Alloc=std::allocator<unsigned char> >
struct bit_aligned_image5_type { typedef ... type; };
Iterators and views
Here ChannelValue models ChannelValueConcept. We don’t need
IsYStep because GIL’s memory-based locator and view already allow
the vertical step to be specified dynamically. Iterators and views can
be constructed from a pixel type:
template <typename Pixel, bool IsPlanar=false, bool IsStep=false, bool IsMutable=true>
struct iterator_type_from_pixel { typedef ... type; };
template <typename Pixel, bool IsPlanar=false, bool IsStepX=false, bool IsMutable=true>
struct view_type_from_pixel { typedef ... type; };
Using a heterogeneous pixel type will result in heterogeneous iterators and views. Types can also be constructed from horizontal iterator:
template <typename XIterator>
struct type_from_x_iterator
{
typedef ... step_iterator_t;
typedef ... xy_locator_t;
typedef ... view_t;
};
Pixel components
You can get pixel-related types of any pixel-based GIL constructs (pixels,
iterators, locators and views) using the following metafunctions provided by
PixelBasedConcept, HomogeneousPixelBasedConcept and metafunctions
built on top of them:
template <typename T> struct color_space_type { typedef ... type; };
template <typename T> struct channel_mapping_type { typedef ... type; };
template <typename T> struct is_planar { typedef ... type; };
// Defined by homogeneous constructs
template <typename T> struct channel_type { typedef ... type; };
template <typename T> struct num_channels { typedef ... type; };
Deriving and manipulating existing types
There are metafunctions to construct the type of a construct from an existing type by changing one or more of its properties:
template <typename PixelReference,
typename ChannelValue, typename Layout, typename IsPlanar, typename IsMutable>
struct derived_pixel_reference_type
{
typedef ... type; // Models PixelConcept
};
template <typename Iterator,
typename ChannelValue, typename Layout, typename IsPlanar, typename IsStep, typename IsMutable>
struct derived_iterator_type
{
typedef ... type; // Models PixelIteratorConcept
};
template <typename View,
typename ChannelValue, typename Layout, typename IsPlanar, typename IsXStep, typename IsMutable>
struct derived_view_type
{
typedef ... type; // Models ImageViewConcept
};
template <typename Image,
typename ChannelValue, typename Layout, typename IsPlanar>
struct derived_image_type
{
typedef ... type; // Models ImageConcept
};
You can replace one or more of its properties and use boost::use_default
for the rest. In this case IsPlanar, IsStep and IsMutable are
MPL boolean constants. For example, here is how to create the type of a view
just like View, but being grayscale and planar:
using VT = typename derived_view_type<View, boost::use_default, gray_t, mp11::mp_true>::type;
Type traits
These are metafunctions, some of which return integral types which can be evaluated like this:
static_assert(is_planar<rgb8_planar_view_t>::value == true, "");
GIL also supports type analysis metafunctions of the form:
[pixel_reference/iterator/locator/view/image] + "_is_" + [basic/mutable/step]
For example:
if (view_is_mutable<View>::value)
{
...
}
A basic GIL construct is a memory-based construct that uses the built-in GIL classes and does not have any function object to invoke upon dereferencing. For example, a simple planar or interleaved, step or non-step RGB image view is basic, but a color converted view or a virtual view is not.