123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242 |
- Metafunctions
- =============
- .. contents::
- :local:
- :depth: 2
- 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:
- .. code-block:: cpp
- 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:
- .. code-block:: cpp
- 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:
- .. code-block:: cpp
- 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:
- .. code-block:: cpp
- 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:
- .. code-block:: cpp
- 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:
- .. code-block:: cpp
- 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:
- .. code-block:: cpp
- 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:
- .. code-block:: cpp
- using VT = typename derived_view_type<View, boost::use_default, gray_t, mpl::true_>::type;
- Type traits
- -----------
- These are metafunctions, some of which return integral types which can be
- evaluated like this:
- .. code-block:: cpp
- static_assert(is_planar<rgb8_planar_view_t>::value == true, "");
- GIL also supports type analysis metafunctions of the form:
- .. code-block:: cpp
- [pixel_reference/iterator/locator/view/image] + "_is_" + [basic/mutable/step]
- For example:
- .. code-block:: cpp
- 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.
|