boost-react-native-bundle

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> <head> <TITLE>Generic Image Library: Generic Image Library Design Guide</TITLE> <META HTTP-EQUIV="content-type" CONTENT="text/html;charset=ISO-8859-1"/> <LINK TYPE="text/css" REL="stylesheet" HREF="adobe_source.css"/> </head> <body> <table border="0" cellspacing="0" cellpadding="0" style='width: 100%; margin: 0; padding: 0'><tr> <td width="100%" valign="top" style='padding-left: 10px; padding-right: 10px; padding-bottom: 10px'> <div class="qindex"><a class="qindex" href="index.html">Modules</a> | <a class="qindex" href="classes.html">Alphabetical List</a> | <a class="qindex" href="annotated.html">Class List</a> | <a class="qindex" href="dirs.html">Directories</a> | <a class="qindex" href="files.html">File List</a> | <a class="qindex" href="../index.html">GIL Home Page</a> </div>   <div class="contents"> <h1><a class="anchor" name="GILDesignGuide">Generic Image Library Design Guide </a></h1><dl class="author" compact><dt>Author:</dt><dd>Lubomir Bourdev (<a href="mailto:lbourdev@adobe.com">lbourdev@adobe.com</a>) and Hailin Jin (<a href="mailto:hljin@adobe.com">hljin@adobe.com</a>) Adobe Systems Incorporated </dd></dl> <dl class="version" compact><dt>Version:</dt><dd>2.1 </dd></dl> <dl class="date" compact><dt>Date:</dt><dd>September 15, 2007</dd></dl> This document describes the design of the Generic Image Library, a C++ image-processing library that abstracts image representation from algorithms on images. It covers more than you need to know for a causal use of GIL. You can find a quick, jump-start GIL tutorial on the main GIL page at <a href="http://stlab.adobe.com/gil">http://stlab.adobe.com/gil</a> <ul> <li><a class="el" href="gildesignguide.html#OverviewSectionDG">1. Overview</a></li><li><a class="el" href="gildesignguide.html#ConceptsSectionDG">2. About Concepts</a></li><li><a class="el" href="gildesignguide.html#PointSectionDG">3. Point</a></li><li><a class="el" href="gildesignguide.html#ChannelSectionDG">4. Channel</a></li><li><a class="el" href="gildesignguide.html#ColorSpaceSectionDG">5. Color Space and Layout</a></li><li><a class="el" href="gildesignguide.html#ColorBaseSectionDG">6. Color Base</a></li><li><a class="el" href="gildesignguide.html#PixelSectionDG">7. Pixel</a></li><li><a class="el" href="gildesignguide.html#PixelIteratorSectionDG">8. Pixel Iterator</a><ul> <li><a class="el" href="gildesignguide.html#FundamentalIteratorDG">Fundamental Iterator</a></li><li><a class="el" href="gildesignguide.html#IteratorAdaptorDG">Iterator Adaptor</a></li><li><a class="el" href="gildesignguide.html#PixelDereferenceAdaptorAG">Pixel Dereference Adaptor</a></li><li><a class="el" href="gildesignguide.html#StepIteratorDG">Step Iterator</a></li><li><a class="el" href="gildesignguide.html#LocatorDG">Pixel Locator</a></li><li><a class="el" href="gildesignguide.html#IteratorFrom2DDG">Iterator over 2D image</a></li></ul> </li><li><a class="el" href="gildesignguide.html#ImageViewSectionDG">9. Image View</a><ul> <li><a class="el" href="gildesignguide.html#ImageViewFrowRawDG">Creating Views from Raw Pixels</a></li><li><a class="el" href="gildesignguide.html#ImageViewFrowImageViewDG">Creating Image Views from Other Image Views</a></li></ul> </li><li><a class="el" href="gildesignguide.html#ImageSectionDG">10. Image</a></li><li><a class="el" href="gildesignguide.html#VariantSecDG">11. Run-time specified images and image views</a></li><li><a class="el" href="gildesignguide.html#MetafunctionsDG">12. Useful Metafunctions and Typedefs</a></li><li><a class="el" href="gildesignguide.html#IO_DG">13. I/O Extension</a></li><li><a class="el" href="gildesignguide.html#SampleImgCodeDG">14. Sample Code</a><ul> <li><a class="el" href="gildesignguide.html#PixelLevelExampleDG">Pixel-level Sample Code</a></li><li><a class="el" href="gildesignguide.html#SafeAreaExampleDG">Creating a Copy of an Image with a Safe Buffer</a></li><li><a class="el" href="gildesignguide.html#HistogramExampleDG">Histogram</a></li><li><a class="el" href="gildesignguide.html#ImageViewsExampleDG">Using Image Views</a></li></ul> </li><li><a class="el" href="gildesignguide.html#ExtendingGIL_DG">15. Extending the Generic Image Library</a><ul> <li><a class="el" href="gildesignguide.html#NewColorSpacesDG">Defining New Color Spaces</a></li><li><a class="el" href="gildesignguide.html#NewColorConversionDG">Overloading Color Conversion</a></li><li><a class="el" href="gildesignguide.html#NewChannelsDG">Defining New Channel Types</a></li><li><a class="el" href="gildesignguide.html#NewImagesDG">Defining New Image Views</a></li></ul> </li><li><a class="el" href="gildesignguide.html#TechnicalitiesDG">16. Technicalities</a></li><li><a class="el" href="gildesignguide.html#ConclusionDG">17. Conclusion</a></li></ul> <hr> <h2><a class="anchor" name="OverviewSectionDG"> 1. Overview</a></h2> Images are essential in any image processing, vision and video project, and yet the variability in image representations makes it difficult to write imaging algorithms that are both generic and efficient. In this section we will describe some of the challenges that we would like to address. In the following discussion an image is a 2D array of pixels. A pixel is a set of color channels that represents the color at a given point in an image. Each channel represents the value of a color component. There are two common memory structures for an image. Interleaved images are represented by grouping the pixels together in memory and interleaving all channels together, whereas planar images keep the channels in separate color planes. Here is a 4x3 RGB image in which the second pixel of the first row is marked in red, in interleaved form: <div align="center"> <img src="interleaved.jpg" alt="interleaved.jpg"> </div> and in planar form: <div align="center"> <img src="planar.jpg" alt="planar.jpg"> </div> Note also that rows may optionally be aligned resulting in a potential padding at the end of rows. The Generic Image Library (GIL) provides models for images that vary in:<ul> <li>Structure (planar vs. interleaved)</li><li>Color space and presence of alpha (RGB, RGBA, CMYK, etc.)</li><li>Channel depth (8-bit, 16-bit, etc.)</li><li>Order of channels (RGB vs. BGR, etc.)</li><li>Row alignment policy (no alignment, word-alignment, etc.)</li></ul> It also supports user-defined models of images, and images whose parameters are specified at run-time. GIL abstracts image representation from algorithms applied on images and allows us to write the algorithm once and have it work on any of the above image variations while generating code that is comparable in speed to that of hand-writing the algorithm for a specific image type. This document follows bottom-up design. Each section defines concepts that build on top of concepts defined in previous sections. It is recommended to read the sections in order. <hr> <h2><a class="anchor" name="ConceptsSectionDG"> 2. About Concepts</a></h2> All constructs in GIL are models of GIL concepts. A concept is a set of requirements that a type (or a set of related types) must fulfill to be used correctly in generic algorithms. The requirements include syntactic and algorithming guarantees. For example, GIL's class <code>pixel</code> is a model of GIL's <code>PixelConcept</code>. The user may substitute the pixel class with one of their own, and, as long as it satisfies the requirements of <code>PixelConcept</code>, all other GIL classes and algorithms can be used with it. See more about concepts here: <a href="http://www.generic-programming.org/languages/conceptcpp/">http://www.generic-programming.org/languages/conceptcpp/</a> In this document we will use a syntax for defining concepts that is described in a proposal for a Concepts extension to C++0x specified here: <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2081.pdf">http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2081.pdf</a> Here are some common concepts that will be used in GIL. Most of them are defined here: <a href="http://www.generic-programming.org/languages/conceptcpp/concept_web.php">http://www.generic-programming.org/languages/conceptcpp/concept_web.php</a> <div class="fragment"><pre class="fragment">auto concept DefaultConstructible<typename T> { T::T(); }; auto concept CopyConstructible<typename T> { T::T(T); T::~T(); }; auto concept Assignable<typename T, typename U = T> { typename result_type; result_type operator=(T&, U); }; auto concept EqualityComparable<typename T, typename U = T> { bool operator==(T x, T y); bool operator!=(T x, T y) { return !(x==y); } }; concept SameType<typename T, typename U> { /* unspecified */ }; template<typename T> concept_map SameType<T, T> { /* unspecified */ }; auto concept Swappable<typename T> { void swap(T& t, T& u); }; </pre></div> Here are some additional basic concepts that GIL needs: <div class="fragment"><pre class="fragment">auto concept Regular<typename T> : DefaultConstructible<T>, CopyConstructible<T>, EqualityComparable<T>, Assignable<T>, Swappable<T> {}; auto concept Metafunction<typename T> { typename type; }; </pre></div><h2><a class="anchor" name="PointSectionDG"> 3. Point</a></h2> A point defines the location of a pixel inside an image. It can also be used to describe the dimensions of an image. In most general terms, points are N-dimensional and model the following concept: <div class="fragment"><pre class="fragment">concept PointNDConcept<typename T> : Regular<T> { // the type of a coordinate along each axis template <size_t K> struct axis; where Metafunction<axis>; const size_t num_dimensions; // accessor/modifier of the value of each axis. template <size_t K> const typename axis<K>::type& T::axis_value() const; template <size_t K> typename axis<K>::type& T::axis_value(); }; </pre></div> GIL uses a two-dimensional point, which is a refinement of <code>PointNDConcept</code> in which both dimensions are of the same type: <div class="fragment"><pre class="fragment">concept Point2DConcept<typename T> : PointNDConcept<T> { where num_dimensions == 2; where SameType<axis<0>::type, axis<1>::type>; typename value_type = axis<0>::type; const value_type& operator[](const T&, size_t i); value_type& operator[]( T&, size_t i); value_type x,y; }; </pre></div> Related Concepts: <ul> <li>PointNDConcept<T></li><li>Point2DConcept<T></li></ul> Models: GIL provides a model of <code>Point2DConcept</code>, <code>point2<T></code> where <code>T</code> is the coordinate type. <hr> <h2><a class="anchor" name="ChannelSectionDG"> 4. Channel</a></h2> A channel indicates the intensity of a color component (for example, the red channel in an RGB pixel). Typical channel operations are getting, comparing and setting the channel values. Channels have associated minimum and maximum value. GIL channels model the following concept: <div class="fragment"><pre class="fragment">concept ChannelConcept<typename T> : EqualityComparable<T> { typename value_type = T; // use channel_traits<T>::value_type to access it where ChannelValueConcept<value_type>; typename reference = T&; // use channel_traits<T>::reference to access it typename pointer = T*; // use channel_traits<T>::pointer to access it typename const_reference = const T&; // use channel_traits<T>::const_reference to access it typename const_pointer = const T*; // use channel_traits<T>::const_pointer to access it static const bool is_mutable; // use channel_traits<T>::is_mutable to access it static T min_value(); // use channel_traits<T>::min_value to access it static T max_value(); // use channel_traits<T>::min_value to access it }; concept MutableChannelConcept<ChannelConcept T> : Swappable<T>, Assignable<T> {}; concept ChannelValueConcept<ChannelConcept T> : Regular<T> {}; </pre></div> GIL allows built-in integral and floating point types to be channels. Therefore the associated types and range information are defined in <code>channel_traits</code> with the following default implementation: <div class="fragment"><pre class="fragment">template <typename T> struct channel_traits { typedef T value_type; typedef T& reference; typedef T* pointer; typedef T& const const_reference; typedef T* const const_pointer; static value_type min_value() { return std::numeric_limits<T>::min(); } static value_type max_value() { return std::numeric_limits<T>::max(); } }; </pre></div> Two channel types are compatible if they have the same value type: <div class="fragment"><pre class="fragment">concept ChannelsCompatibleConcept<ChannelConcept T1, ChannelConcept T2> { where SameType<T1::value_type, T2::value_type>; }; </pre></div> A channel may be convertible to another channel: <div class="fragment"><pre class="fragment">template <ChannelConcept Src, ChannelValueConcept Dst> concept ChannelConvertibleConcept { Dst <a class="code" href="g_i_l_0099.html#gf04e6ac30a35a1f68a8bb84730e34786" title="Converting from one channel type to another.">channel_convert</a>(Src); }; </pre></div> Note that <code>ChannelConcept</code> and <code>MutableChannelConcept</code> do not require a default constructor. Channels that also support default construction (and thus are regular types) model <code>ChannelValueConcept</code>. To understand the motivation for this distinction, consider a 16-bit RGB pixel in a "565" bit pattern. Its channels correspond to bit ranges. To support such channels, we need to create a custom proxy class corresponding to a reference to a subbyte channel. Such a proxy reference class models only <code>ChannelConcept</code>, because, similar to native C++ references, it may not have a default constructor. Note also that algorithms may impose additional requirements on channels, such as support for arithmentic operations. Related Concepts: <ul> <li>ChannelConcept<T></li><li>ChannelValueConcept<T></li><li>MutableChannelConcept<T></li><li>ChannelsCompatibleConcept<T1,T2></li><li>ChannelConvertibleConcept<SrcChannel,DstChannel></li></ul> Models: All built-in integral and floating point types are valid channels. GIL provides standard typedefs for some integral channels: <div class="fragment"><pre class="fragment">typedef boost::uint8_t bits8; typedef boost::uint16_t bits16; typedef boost::uint32_t bits32; typedef boost::int8_t bits8s; typedef boost::int16_t bits16s; typedef boost::int32_t bits32s; </pre></div> The minimum and maximum values of a channel modeled by a built-in type correspond to the minimum and maximum physical range of the built-in type, as specified by its <code>std::numeric_limits</code>. Sometimes the physical range is not appropriate. GIL provides <code>scoped_channel_value</code>, a model for a channel adapter that allows for specifying a custom range. We use it to define a [0..1] floating point channel type as follows: <div class="fragment"><pre class="fragment">struct float_zero { static float apply() { return 0.0f; } }; struct float_one { static float apply() { return 1.0f; } }; typedef scoped_channel_value<float,float_zero,float_one> bits32f; </pre></div> GIL also provides models for channels corresponding to ranges of bits: <div class="fragment"><pre class="fragment">// Value of a channel defined over NumBits bits. Models ChannelValueConcept template <int NumBits> class packed_channel_value; // Reference to a channel defined over NumBits bits. Models ChannelConcept template <int FirstBit, int NumBits, // Defines the sequence of bits in the data value that contain the channel bool Mutable> // true if the reference is mutable class packed_channel_reference; // Reference to a channel defined over NumBits bits. Its FirstBit is a run-time parameter. Models ChannelConcept template <int NumBits, // Defines the sequence of bits in the data value that contain the channel bool Mutable> // true if the reference is mutable class packed_dynamic_channel_reference; </pre></div> Note that there are two models of a reference proxy which differ based on whether the offset of the channel range is specified as a template or a run-time parameter. The first model is faster and more compact while the second model is more flexible. For example, the second model allows us to construct an iterator over bitrange channels. Algorithms: Here is how to construct the three channels of a 16-bit "565" pixel and set them to their maximum value: <div class="fragment"><pre class="fragment">typedef packed_channel_reference<0,5,true> channel16_0_5_reference_t; typedef packed_channel_reference<5,6,true> channel16_5_6_reference_t; typedef packed_channel_reference<11,5,true> channel16_11_5_reference_t; boost::uint16_t data=0; channel16_0_5_reference_t channel1(&data); channel16_5_6_reference_t channel2(&data); channel16_11_5_reference_t channel3(&data); channel1=channel_traits<channel16_0_5_reference_t>::max_value(); channel2=channel_traits<channel16_5_6_reference_t>::max_value(); channel3=channel_traits<channel16_11_5_reference_t>::max_value(); assert(data==65535); </pre></div> Assignment, equality comparison and copy construction are defined only between compatible channels: <div class="fragment"><pre class="fragment">packed_channel_value<5> channel_6bit = channel1; channel_6bit = channel3; //channel_6bit = channel2; // compile error: Assignment between incompatible channels. </pre></div> All channel models provided by GIL are pairwise convertible: <div class="fragment"><pre class="fragment">channel1 = channel_traits<channel16_0_5_reference_t>::max_value(); assert(channel1 == 31); bits16 chan16 = channel_convert<bits16>(channel1); assert(chan16 == 65535); </pre></div> Channel conversion is a lossy operation. GIL's channel conversion is a linear transformation between the ranges of the source and destination channel. It maps precisely the minimum to the minimum and the maximum to the maximum. (For example, to convert from uint8_t to uint16_t GIL does not do a bit shift because it will not properly match the maximum values. Instead GIL multiplies the source by 257). All channel models that GIL provides are convertible from/to an integral or floating point type. Thus they support arithmetic operations. Here are the channel-level algorithms that GIL provides: <div class="fragment"><pre class="fragment">// Converts a source channel value into a destrination channel. Linearly maps the value of the source // into the range of the destination template <typename DstChannel, typename SrcChannel> typename channel_traits<DstChannel>::value_type <a class="code" href="g_i_l_0099.html#gf04e6ac30a35a1f68a8bb84730e34786" title="Converting from one channel type to another.">channel_convert</a>(SrcChannel src); // returns max_value - x + min_value template <typename Channel> typename channel_traits<Channel>::value_type <a class="code" href="g_i_l_0101.html#ge2e0267865f89610ef26148874a04bb5" title="Default implementation. Provide overloads for performance.">channel_invert</a>(Channel x); // returns a * b / max_value template <typename Channel> typename channel_traits<Channel>::value_type <a class="code" href="g_i_l_0103.html#gf73b2a47a7877767534df0eee46dda17" title="A function multiplying two channels. result = a * b / max_value.">channel_multiply</a>(Channel a, Channel b); </pre></div> <hr> <h2><a class="anchor" name="ColorSpaceSectionDG"> 5. Color Space and Layout</a></h2> A color space captures the set and interpretation of channels comprising a pixel. It is an MPL random access sequence containing the types of all elements in the color space. Two color spaces are considered compatible if they are equal (i.e. have the same set of colors in the same order). Related Concepts: <ul> <li>ColorSpaceConcept<ColorSpace></li><li>ColorSpacesCompatibleConcept<ColorSpace1,ColorSpace2></li><li>ChannelMappingConcept<Mapping></li></ul> Models: GIL currently provides the following color spaces: <code>gray_t</code>, <code>rgb_t</code>, <code>rgba_t</code>, and <code>cmyk_t</code>. It also provides unnamed N-channel color spaces of two to five channels, <code>devicen_t<2></code>, <code>devicen_t<3></code>, <code>devicen_t<4></code>, <code>devicen_t<5></code>. Besides the standard layouts, it provides <code>bgr_layout_t</code>, <code>bgra_layout_t</code>, <code>abgr_layout_t</code> and <code>argb_layout_t</code>. As an example, here is how GIL defines the RGBA color space: <div class="fragment"><pre class="fragment">struct red_t{}; struct green_t{}; struct blue_t{}; struct alpha_t{}; typedef mpl::vector4<red_t,green_t,blue_t,alpha_t> rgba_t; </pre></div> The ordering of the channels in the color space definition specifies their semantic order. For example, <code>red_t</code> is the first semantic channel of <code>rgba_t</code>. While there is a unique semantic ordering of the channels in a color space, channels may vary in their physical ordering in memory. The mapping of channels is specified by <code>ChannelMappingConcept</code>, which is an MPL random access sequence of integral types. A color space and its associated mapping are often used together. Thus they are grouped in GIL's layout: <div class="fragment"><pre class="fragment">template <typename ColorSpace, typename ChannelMapping = mpl::range_c<int,0,mpl::size<ColorSpace>::value> > struct layout { typedef ColorSpace color_space_t; typedef ChannelMapping channel_mapping_t; }; </pre></div> Here is how to create layouts for the RGBA color space: <div class="fragment"><pre class="fragment">typedef layout<rgba_t> rgba_layout_t; // default ordering is 0,1,2,3... typedef layout<rgba_t, mpl::vector4_c<int,2,1,0,3> > bgra_layout_t; typedef layout<rgba_t, mpl::vector4_c<int,1,2,3,0> > argb_layout_t; typedef layout<rgba_t, mpl::vector4_c<int,3,2,1,0> > abgr_layout_t; </pre></div> <hr> <h2><a class="anchor" name="ColorBaseSectionDG"> 6. Color Base</a></h2> A color base is a container of color elements. The most common use of color base is in the implementation of a pixel, in which case the color elements are channel values. The color base concept, however, can be used in other scenarios. For example, a planar pixel has channels that are not contiguous in memory. Its reference is a proxy class that uses a color base whose elements are channel references. Its iterator uses a color base whose elements are channel iterators. Color base models must satisfy the following concepts: <div class="fragment"><pre class="fragment">concept ColorBaseConcept<typename T> : CopyConstructible<T>, EqualityComparable<T> { // a GIL layout (the color space and element permutation) typename layout_t; // The type of K-th element template <int K> struct kth_element_type; where Metafunction<kth_element_type>; // The result of at_c template <int K> struct kth_element_const_reference_type; where Metafunction<kth_element_const_reference_type>; template <int K> kth_element_const_reference_type<T,K>::type at_c(T); template <ColorBaseConcept T2> where { ColorBasesCompatibleConcept<T,T2> } T::T(T2); template <ColorBaseConcept T2> where { ColorBasesCompatibleConcept<T,T2> } bool operator==(const T&, const T2&); template <ColorBaseConcept T2> where { ColorBasesCompatibleConcept<T,T2> } bool operator!=(const T&, const T2&); }; concept MutableColorBaseConcept<ColorBaseConcept T> : Assignable<T>, Swappable<T> { template <int K> struct kth_element_reference_type; where Metafunction<kth_element_reference_type>; template <int K> kth_element_reference_type<T,K>::type at_c(T); template <ColorBaseConcept T2> where { ColorBasesCompatibleConcept<T,T2> } T& operator=(T&, const T2&); }; concept ColorBaseValueConcept<typename T> : MutableColorBaseConcept<T>, Regular<T> { }; concept HomogeneousColorBaseConcept<ColorBaseConcept CB> { // For all K in [0 ... size<C1>::value-1): // where SameType<kth_element_type<K>::type, kth_element_type<K+1>::type>; kth_element_const_reference_type<0>::type dynamic_at_c(const CB&, std::size_t n) const; }; concept MutableHomogeneousColorBaseConcept<MutableColorBaseConcept CB> : HomogeneousColorBaseConcept<CB> { kth_element_reference_type<0>::type dynamic_at_c(const CB&, std::size_t n); }; concept HomogeneousColorBaseValueConcept<typename T> : MutableHomogeneousColorBaseConcept<T>, Regular<T> { }; concept ColorBasesCompatibleConcept<ColorBaseConcept C1, ColorBaseConcept C2> { where SameType<C1::layout_t::color_space_t, C2::layout_t::color_space_t>; // also, for all K in [0 ... size<C1>::value): // where Convertible<kth_semantic_element_type<C1,K>::type, kth_semantic_element_type<C2,K>::type>; // where Convertible<kth_semantic_element_type<C2,K>::type, kth_semantic_element_type<C1,K>::type>; }; </pre></div> A color base must have an associated layout (which consists of a color space, as well as an ordering of the channels). There are two ways to index the elements of a color base: A physical index corresponds to the way they are ordered in memory, and a semantic index corresponds to the way the elements are ordered in their color space. For example, in the RGB color space the elements are ordered as {red_t, green_t, blue_t}. For a color base with a BGR layout, the first element in physical ordering is the blue element, whereas the first semantic element is the red one. Models of <code>ColorBaseConcept</code> are required to provide the <code>at_c<K>(ColorBase)</code> function, which allows for accessing the elements based on their physical order. GIL provides a <code>semantic_at_c<K>(ColorBase)</code> function (described later) which can operate on any model of ColorBaseConcept and returns the corresponding semantic element. Two color bases are compatible if they have the same color space and their elements (paired semantically) are convertible to each other. Models: GIL provides a model for a homogeneous color base (a color base whose elements all have the same type). <div class="fragment"><pre class="fragment">namespace detail { template <typename Element, typename Layout, int K> struct homogeneous_color_base; } </pre></div> It is used in the implementation of GIL's pixel, planar pixel reference and planar pixel iterator. Another model of <code>ColorBaseConcept</code> is <code>packed_pixel</code> - it is a pixel whose channels are bit ranges. See the <a class="el" href="gildesignguide.html#PixelSectionDG">7. Pixel</a> section for more. Algorithms: GIL provides the following functions and metafunctions operating on color bases: <div class="fragment"><pre class="fragment">// Metafunction returning an mpl::int_ equal to the number of elements in the color base template <class ColorBase> struct size; // Returns the type of the return value of semantic_at_c<K>(color_base) template <class ColorBase, int K> struct kth_semantic_element_reference_type; template <class ColorBase, int K> struct kth_semantic_element_const_reference_type; // Returns a reference to the element with K-th semantic index. template <class ColorBase, int K> typename kth_semantic_element_reference_type<ColorBase,K>::type <a class="code" href="g_i_l_0114.html#g2cdd9bfd1b27576659b8c79a3a0233de" title="A mutable accessor to the K-th semantic element of a color base.">semantic_at_c</a>(ColorBase& p) template <class ColorBase, int K> typename kth_semantic_element_const_reference_type<ColorBase,K>::type <a class="code" href="g_i_l_0114.html#g2cdd9bfd1b27576659b8c79a3a0233de" title="A mutable accessor to the K-th semantic element of a color base.">semantic_at_c</a>(const ColorBase& p) // Returns the type of the return value of get_color<Color>(color_base) template <typename Color, typename ColorBase> struct color_reference_t; template <typename Color, typename ColorBase> struct color_const_reference_t; // Returns a reference to the element corresponding to the given color template <typename ColorBase, typename Color> typename color_reference_t<Color,ColorBase>::type <a class="code" href="g_i_l_0106.html#gab1205781ba628ca806c47a51f40f5f6" title="Mutable accessor to the element associated with a given color name.">get_color</a>(ColorBase& cb, Color=Color()); template <typename ColorBase, typename Color> typename color_const_reference_t<Color,ColorBase>::type <a class="code" href="g_i_l_0106.html#gab1205781ba628ca806c47a51f40f5f6" title="Mutable accessor to the element associated with a given color name.">get_color</a>(const ColorBase& cb, Color=Color()); // Returns the element type of the color base. Defined for homogeneous color bases only template <typename ColorBase> struct element_type; template <typename ColorBase> struct element_reference_type; template <typename ColorBase> struct element_const_reference_type; </pre></div> GIL also provides the following algorithms which operate on color bases. Note that they all pair the elements semantically: <div class="fragment"><pre class="fragment">// Equivalents to std::equal, std::copy, std::fill, std::generate template <typename CB1,typename CB2> bool static_equal(const CB1& p1, const CB2& p2); template <typename Src,typename Dst> void static_copy(const Src& src, Dst& dst); template <typename CB, typename Op> void static_generate(CB& dst,Op op); // Equivalents to std::transform template <typename CB , typename Dst,typename Op> Op static_transform( CB&,Dst&,Op); template <typename CB , typename Dst,typename Op> Op static_transform(const CB&,Dst&,Op); template <typename CB1,typename CB2,typename Dst,typename Op> Op static_transform( CB1&, CB2&,Dst&,Op); template <typename CB1,typename CB2,typename Dst,typename Op> Op static_transform(const CB1&, CB2&,Dst&,Op); template <typename CB1,typename CB2,typename Dst,typename Op> Op static_transform( CB1&,const CB2&,Dst&,Op); template <typename CB1,typename CB2,typename Dst,typename Op> Op static_transform(const CB1&,const CB2&,Dst&,Op); // Equivalents to std::for_each template <typename CB1, typename Op> Op static_for_each( CB1&,Op); template <typename CB1, typename Op> Op static_for_each(const CB1&,Op); template <typename CB1,typename CB2, typename Op> Op static_for_each( CB1&, CB2&,Op); template <typename CB1,typename CB2, typename Op> Op static_for_each( CB1&,const CB2&,Op); template <typename CB1,typename CB2, typename Op> Op static_for_each(const CB1&, CB2&,Op); template <typename CB1,typename CB2, typename Op> Op static_for_each(const CB1&,const CB2&,Op); template <typename CB1,typename CB2,typename CB3,typename Op> Op static_for_each( CB1&, CB2&, CB3&,Op); template <typename CB1,typename CB2,typename CB3,typename Op> Op static_for_each( CB1&, CB2&,const CB3&,Op); template <typename CB1,typename CB2,typename CB3,typename Op> Op static_for_each( CB1&,const CB2&, CB3&,Op); template <typename CB1,typename CB2,typename CB3,typename Op> Op static_for_each( CB1&,const CB2&,const CB3&,Op); template <typename CB1,typename CB2,typename CB3,typename Op> Op static_for_each(const CB1&, CB2&, CB3&,Op); template <typename CB1,typename CB2,typename CB3,typename Op> Op static_for_each(const CB1&, CB2&,const CB3&,Op); template <typename CB1,typename CB2,typename CB3,typename Op> Op static_for_each(const CB1&,const CB2&, CB3&,Op); template <typename CB1,typename CB2,typename CB3,typename Op> Op static_for_each(const CB1&,const CB2&,const CB3&,Op); // The following algorithms are only defined for homogeneous color bases: // Equivalent to std::fill template <typename HCB, typename Element> void static_fill(HCB& p, const Element& v); // Equivalents to std::min_element and std::max_element template <typename HCB> typename element_const_reference_type<HCB>::type static_min(const HCB&); template <typename HCB> typename element_reference_type<HCB>::type static_min( HCB&); template <typename HCB> typename element_const_reference_type<HCB>::type static_max(const HCB&); template <typename HCB> typename element_reference_type<HCB>::type static_max( HCB&); </pre></div> These algorithms are designed after the corresponding STL algorithms, except that instead of ranges they take color bases and operate on their elements. In addition, they are implemented with a compile-time recursion (thus the prefix "static_"). Finally, they pair the elements semantically instead of based on their physical order in memory. For example, here is the implementation of <code>static_equal:</code> <div class="fragment"><pre class="fragment">namespace detail { template <int K> struct element_recursion { template <typename P1,typename P2> static bool static_equal(const P1& p1, const P2& p2) { return element_recursion<K-1>::static_equal(p1,p2) && <a class="code" href="g_i_l_0114.html#g2cdd9bfd1b27576659b8c79a3a0233de" title="A mutable accessor to the K-th semantic element of a color base.">semantic_at_c</a><K-1>(p1)==semantic_at_c<N-1>(p2); } }; template <> struct element_recursion<0> { template <typename P1,typename P2> static bool static_equal(const P1&, const P2&) { return true; } }; } template <typename P1,typename P2> bool static_equal(const P1& p1, const P2& p2) { gil_function_requires<ColorSpacesCompatibleConcept<P1::layout_t::color_space_t,P2::layout_t::color_space_t> >(); return detail::element_recursion<size<P1>::value>::static_equal(p1,p2); } </pre></div> This algorithm is used when invoking <code>operator==</code> on two pixels, for example. By using semantic accessors we are properly comparing an RGB pixel to a BGR pixel. Notice also that all of the above algorithms taking more than one color base require that they all have the same color space. <hr> <h2><a class="anchor" name="PixelSectionDG"> 7. Pixel</a></h2> A pixel is a set of channels defining the color at a given point i