boost/gil/channel.hpp

   1 //
   2 // Copyright 2005-2007 Adobe Systems Incorporated
   3 //
   4 // Distributed under the Boost Software License, Version 1.0
   5 // See accompanying file LICENSE_1_0.txt or copy at
   6 // http://www.boost.org/LICENSE_1_0.txt
   7 //
   8 #ifndef BOOST_GIL_CHANNEL_HPP
   9 #define BOOST_GIL_CHANNEL_HPP
  10
  11 #include <boost/gil/utilities.hpp>
  12
  13 #include <boost/assert.hpp>
  14 #include <boost/config.hpp>
  15 #include <boost/config/pragma_message.hpp>
  16 #include <boost/integer/integer_mask.hpp>
  17
  18 #include <cstdint>
  19 #include <limits>
  20 #include <type_traits>
  21
  22 #ifdef BOOST_GIL_DOXYGEN_ONLY
  23 /// \def BOOST_GIL_CONFIG_HAS_UNALIGNED_ACCESS
  24 /// \brief Define to allow unaligned memory access for models of packed channel value.
  25 /// Theoretically (or historically?) on platforms which support dereferencing on
  26 /// non-word memory boundary, unaligned access may result in performance improvement.
  27 /// \warning Unfortunately, this optimization may be a C/C++ strict aliasing rules
  28 /// violation, if accessed data buffer has effective type that cannot be aliased
  29 /// without leading to undefined behaviour.
  30 #define BOOST_GIL_CONFIG_HAS_UNALIGNED_ACCESS
  31 #endif
  32
  33 #ifdef BOOST_GIL_CONFIG_HAS_UNALIGNED_ACCESS
  34 #if defined(sun) || defined(__sun) || \             // SunOS
  35     defined(__osf__) || defined(__osf) || \         // Tru64
  36     defined(_hpux) || defined(hpux) || \            // HP-UX
  37     defined(__arm__) || defined(__ARM_ARCH) || \    // ARM
  38     defined(_AIX)                                   // AIX
  39 #error Unaligned access strictly disabled for some UNIX platforms or ARM architecture
  40 #elif defined(__i386__) || defined(__x86_64__) || defined(__vax__)
  41     // The check for little-endian architectures that tolerate unaligned memory
  42     // accesses is just an optimization. Nothing will break if it fails to detect
  43     // a suitable architecture.
  44     //
  45     // Unfortunately, this optimization may be a C/C++ strict aliasing rules violation
  46     // if accessed data buffer has effective type that cannot be aliased
  47     // without leading to undefined behaviour.
  48 BOOST_PRAGMA_MESSAGE("CAUTION: Unaligned access tolerated on little-endian may cause undefined behaviour")
  49 #else
  50 #error Unaligned access disabled for unknown platforms and architectures
  51 #endif
  52 #endif // defined(BOOST_GIL_CONFIG_HAS_UNALIGNED_ACCESS)
  53
  54 namespace boost { namespace gil {
  55
  56 ///////////////////////////////////////////
  57 ////  channel_traits
  58 ////
  59 ////  \ingroup ChannelModel
  60 ////  \class channel_traits
  61 ////  \brief defines properties of channels, such as their range and associated types
  62 ////
  63 ////  The channel traits must be defined for every model of ChannelConcept
  64 ////  Default traits are provided. For built-in types the default traits use
  65 ////  built-in pointer and reference and the channel range is the physical
  66 ////  range of the type. For classes, the default traits forward the associated types
  67 ////  and range to the class.
  68 ////
  69 ///////////////////////////////////////////
  70
  71 namespace detail {
  72
  73 template <typename T, bool IsClass>
  74 struct channel_traits_impl;
  75
  76 // channel traits for custom class
  77 template <typename T>
  78 struct channel_traits_impl<T, true>
  79 {
  80     using value_type = typename T::value_type;
  81     using reference = typename T::reference;
  82     using pointer = typename T::pointer;
  83     using const_reference = typename T::const_reference;
  84     using const_pointer = typename T::const_pointer;
  85     static constexpr bool is_mutable = T::is_mutable;
  86     static value_type min_value() { return T::min_value(); }
  87     static value_type max_value() { return T::max_value(); }
  88 };
  89
  90 // channel traits implementation for built-in integral or floating point channel type
  91 template <typename T>
  92 struct channel_traits_impl<T, false>
  93 {
  94     using value_type = T;
  95     using reference = T&;
  96     using pointer = T*;
  97     using const_reference = T const&;
  98     using const_pointer = T const*;
  99     static constexpr bool is_mutable = true;
 100     static value_type min_value() { return (std::numeric_limits<T>::min)(); }
 101     static value_type max_value() { return (std::numeric_limits<T>::max)(); }
 102 };
 103
 104 // channel traits implementation for constant built-in scalar or floating point type
 105 template <typename T>
 106 struct channel_traits_impl<T const, false> : channel_traits_impl<T, false>
 107 {
 108     using reference = T const&;
 109     using pointer = T const*;
 110     static constexpr bool is_mutable = false;
 111 };
 112
 113 } // namespace detail
 114
 115 /**
 116 \ingroup ChannelModel
 117 \brief Traits for channels. Contains the following members:
 118 \code
 119 template <typename Channel>
 120 struct channel_traits {
 121     using value_type = ...;
 122     using reference = ...;
 123     using pointer = ...;
 124     using const_reference = ...;
 125     using const_pointer = ...;
 126
 127     static const bool is_mutable;
 128     static value_type min_value();
 129     static value_type max_value();
 130 };
 131 \endcode
 132 */
 133 template <typename T>
 134 struct channel_traits : detail::channel_traits_impl<T, std::is_class<T>::value> {};
 135
 136 // Channel traits for C++ reference type - remove the reference
 137 template <typename T>
 138 struct channel_traits<T&> : channel_traits<T> {};
 139
 140 // Channel traits for constant C++ reference type
 141 template <typename T>
 142 struct channel_traits<T const&> : channel_traits<T>
 143 {
 144     using reference = typename channel_traits<T>::const_reference;
 145     using pointer = typename channel_traits<T>::const_pointer;
 146     static constexpr bool is_mutable = false;
 147 };
 148
 149 ///////////////////////////////////////////
 150 ////  scoped_channel_value
 151 ///////////////////////////////////////////
 152
 153 /// \defgroup ScopedChannelValue scoped_channel_value
 154 /// \ingroup ChannelModel
 155 /// \brief A channel adaptor that modifies the range of the source channel. Models: ChannelValueConcept
 156 ///
 157 /// Example:
 158 /// \code
 159 /// // Create a double channel with range [-0.5 .. 0.5]
 160 /// struct double_minus_half  { static double apply() { return -0.5; } };
 161 /// struct double_plus_half   { static double apply() { return  0.5; } };
 162 /// using bits64custom_t = scoped_channel_value<double, double_minus_half, double_plus_half>;
 163 ///
 164 /// // channel_convert its maximum should map to the maximum
 165 /// bits64custom_t x = channel_traits<bits64custom_t>::max_value();
 166 /// assert(x == 0.5);
 167 /// uint16_t y = channel_convert<uint16_t>(x);
 168 /// assert(y == 65535);
 169 /// \endcode
 170
 171 /// \ingroup ScopedChannelValue
 172 /// \brief A channel adaptor that modifies the range of the source channel. Models: ChannelValueConcept
 173 /// \tparam BaseChannelValue base channel (models ChannelValueConcept)
 174 /// \tparam MinVal class with a static apply() function returning the minimum channel values
 175 /// \tparam MaxVal class with a static apply() function returning the maximum channel values
 176 template <typename BaseChannelValue, typename MinVal, typename MaxVal>
 177 struct scoped_channel_value
 178 {
 179     using value_type = scoped_channel_value<BaseChannelValue, MinVal, MaxVal>;
 180     using reference = value_type&;
 181     using pointer = value_type*;
 182     using const_reference = value_type const&;
 183     using const_pointer = value_type const*;
 184     static constexpr bool is_mutable = channel_traits<BaseChannelValue>::is_mutable;
 185
 186     using base_channel_t = BaseChannelValue;
 187
 188     static value_type min_value() { return MinVal::apply(); }
 189     static value_type max_value() { return MaxVal::apply(); }
 190
 191     scoped_channel_value() = default;
 192     scoped_channel_value(scoped_channel_value const& other) : value_(other.value_) {}
 193     scoped_channel_value& operator=(scoped_channel_value const& other) = default;
 194     scoped_channel_value(BaseChannelValue value) : value_(value) {}
 195     scoped_channel_value& operator=(BaseChannelValue value)
 196     {
 197         value_ = value;
 198         return *this;
 199     }
 200
 201     scoped_channel_value& operator++() { ++value_; return *this; }
 202     scoped_channel_value& operator--() { --value_; return *this; }
 203
 204     scoped_channel_value operator++(int) { scoped_channel_value tmp=*this; this->operator++(); return tmp; }
 205     scoped_channel_value operator--(int) { scoped_channel_value tmp=*this; this->operator--(); return tmp; }
 206
 207     template <typename Scalar2> scoped_channel_value& operator+=(Scalar2 v) { value_+=v; return *this; }
 208     template <typename Scalar2> scoped_channel_value& operator-=(Scalar2 v) { value_-=v; return *this; }
 209     template <typename Scalar2> scoped_channel_value& operator*=(Scalar2 v) { value_*=v; return *this; }
 210     template <typename Scalar2> scoped_channel_value& operator/=(Scalar2 v) { value_/=v; return *this; }
 211
 212     operator BaseChannelValue() const { return value_; }
 213 private:
 214     BaseChannelValue value_{};
 215 };
 216
 217 template <typename T>
 218 struct float_point_zero
 219 {
 220     static constexpr T apply() { return 0.0f; }
 221 };
 222
 223 template <typename T>
 224 struct float_point_one
 225 {
 226     static constexpr T apply() { return 1.0f; }
 227 };
 228
 229 ///////////////////////////////////////////
 230 ////  Support for sub-byte channels. These are integral channels whose value is contained in a range of bits inside an integral type
 231 ///////////////////////////////////////////
 232
 233 // It is necessary for packed channels to have their own value type. They cannot simply use an integral large enough to store the data. Here is why:
 234 // - Any operation that requires returning the result by value will otherwise return the built-in integral type, which will have incorrect range
 235 //   That means that after getting the value of the channel we cannot properly do channel_convert, channel_invert, etc.
 236 // - Two channels are declared compatible if they have the same value type. That means that a packed channel is incorrectly declared compatible with an integral type
 237 namespace detail {
 238
 239 // returns the smallest fast unsigned integral type that has at least NumBits bits
 240 template <int NumBits>
 241 struct min_fast_uint :
 242     std::conditional
 243     <
 244         NumBits <= 8,
 245         std::uint_least8_t,
 246         typename std::conditional
 247         <
 248             NumBits <= 16,
 249             std::uint_least16_t,
 250             typename std::conditional
 251             <
 252                 NumBits <= 32,
 253                 std::uint_least32_t,
 254                 std::uintmax_t
 255             >::type
 256         >::type
 257     >
 258 {};
 259
 260 template <int NumBits>
 261 struct num_value_fn
 262     : std::conditional<NumBits < 32, std::uint32_t, std::uint64_t>
 263 {};
 264
 265 template <int NumBits>
 266 struct max_value_fn
 267     : std::conditional<NumBits <= 32, std::uint32_t, std::uint64_t>
 268 {};
 269
 270 } // namespace detail
 271
 272 /// \defgroup PackedChannelValueModel packed_channel_value
 273 /// \ingroup ChannelModel
 274 /// \brief Represents the value of an unsigned integral channel operating over a bit range. Models: ChannelValueConcept
 275 /// Example:
 276 /// \code
 277 /// // A 4-bit unsigned integral channel.
 278 /// using bits4 = packed_channel_value<4>;
 279 ///
 280 /// assert(channel_traits<bits4>::min_value()==0);
 281 /// assert(channel_traits<bits4>::max_value()==15);
 282 /// assert(sizeof(bits4)==1);
 283 /// static_assert(gil::is_channel_integral<bits4>::value, "");
 284 /// \endcode
 285
 286 /// \ingroup PackedChannelValueModel
 287 /// \brief The value of a subbyte channel. Models: ChannelValueConcept
 288 template <int NumBits>
 289 class packed_channel_value
 290 {
 291 public:
 292     using integer_t = typename detail::min_fast_uint<NumBits>::type;
 293
 294     using value_type = packed_channel_value<NumBits>;
 295     using reference = value_type&;
 296     using const_reference = value_type const&;
 297     using pointer = value_type*;
 298     using const_pointer = value_type const*;
 299     static constexpr bool is_mutable = true;
 300
 301     static value_type min_value() { return 0; }
 302     static value_type max_value() { return low_bits_mask_t< NumBits >::sig_bits; }
 303
 304     packed_channel_value() = default;
 305     packed_channel_value(integer_t v)
 306     {
 307         value_ = static_cast<integer_t>(v & low_bits_mask_t<NumBits>::sig_bits_fast);
 308     }
 309
 310     template <typename Scalar>
 311     packed_channel_value(Scalar v)
 312     {
 313         value_ = packed_channel_value(static_cast<integer_t>(v));
 314     }
 315
 316     static unsigned int num_bits() { return NumBits; }
 317
 318     operator integer_t() const { return value_; }
 319
 320 private:
 321     integer_t value_{};
 322 };
 323
 324 namespace detail {
 325
 326 template <std::size_t K>
 327 struct static_copy_bytes
 328 {
 329     void operator()(unsigned char const* from, unsigned char* to) const
 330     {
 331         *to = *from;
 332         static_copy_bytes<K - 1>()(++from, ++to);
 333     }
 334 };
 335
 336 template <>
 337 struct static_copy_bytes<0>
 338 {
 339     void operator()(unsigned char const*, unsigned char*) const {}
 340 };
 341
 342 template <typename Derived, typename BitField, int NumBits, bool IsMutable>
 343 class packed_channel_reference_base
 344 {
 345 protected:
 346     using data_ptr_t = typename std::conditional<IsMutable, void*, void const*>::type;
 347 public:
 348     data_ptr_t _data_ptr;   // void* pointer to the first byte of the bit range
 349
 350     using value_type = packed_channel_value<NumBits>;
 351     using reference = const Derived;
 352     using pointer = value_type *;
 353     using const_pointer = const value_type *;
 354     static constexpr int num_bits = NumBits;
 355     static constexpr bool is_mutable = IsMutable;
 356
 357     static value_type min_value()       { return channel_traits<value_type>::min_value(); }
 358     static value_type max_value()       { return channel_traits<value_type>::max_value(); }
 359
 360     using bitfield_t = BitField;
 361     using integer_t = typename value_type::integer_t;
 362
 363     packed_channel_reference_base(data_ptr_t data_ptr) : _data_ptr(data_ptr) {}
 364     packed_channel_reference_base(const packed_channel_reference_base& ref) : _data_ptr(ref._data_ptr) {}
 365     const Derived& operator=(integer_t v) const { set(v); return derived(); }
 366
 367     const Derived& operator++() const { set(get()+1); return derived(); }
 368     const Derived& operator--() const { set(get()-1); return derived(); }
 369
 370     Derived operator++(int) const { Derived tmp=derived(); this->operator++(); return tmp; }
 371     Derived operator--(int) const { Derived tmp=derived(); this->operator--(); return tmp; }
 372
 373     template <typename Scalar2> const Derived& operator+=(Scalar2 v) const { set( static_cast<integer_t>(  get() + v )); return derived(); }
 374     template <typename Scalar2> const Derived& operator-=(Scalar2 v) const { set( static_cast<integer_t>(  get() - v )); return derived(); }
 375     template <typename Scalar2> const Derived& operator*=(Scalar2 v) const { set( static_cast<integer_t>(  get() * v )); return derived(); }
 376     template <typename Scalar2> const Derived& operator/=(Scalar2 v) const { set( static_cast<integer_t>(  get() / v )); return derived(); }
 377
 378     operator integer_t() const { return get(); }
 379     data_ptr_t operator &() const {return _data_ptr;}
 380 protected:
 381
 382     using num_value_t = typename detail::num_value_fn<NumBits>::type;
 383     using max_value_t = typename detail::max_value_fn<NumBits>::type;
 384
 385     static const num_value_t num_values = static_cast< num_value_t >( 1 ) << NumBits ;
 386     static const max_value_t max_val    = static_cast< max_value_t >( num_values - 1 );
 387
 388 #if defined(BOOST_GIL_CONFIG_HAS_UNALIGNED_ACCESS)
 389     const bitfield_t& get_data()                      const { return *static_cast<const bitfield_t*>(_data_ptr); }
 390     void              set_data(const bitfield_t& val) const {        *static_cast<      bitfield_t*>(_data_ptr) = val; }
 391 #else
 392     bitfield_t get_data() const {
 393         bitfield_t ret;
 394         static_copy_bytes<sizeof(bitfield_t) >()(gil_reinterpret_cast_c<const unsigned char*>(_data_ptr),gil_reinterpret_cast<unsigned char*>(&ret));
 395         return ret;
 396     }
 397     void set_data(const bitfield_t& val) const {
 398         static_copy_bytes<sizeof(bitfield_t) >()(gil_reinterpret_cast_c<const unsigned char*>(&val),gil_reinterpret_cast<unsigned char*>(_data_ptr));
 399     }
 400 #endif
 401
 402 private:
 403     void set(integer_t value) const {     // can this be done faster??
 404         this->derived().set_unsafe(((value % num_values) + num_values) % num_values);
 405     }
 406     integer_t get() const { return derived().get(); }
 407     const Derived& derived() const { return static_cast<const Derived&>(*this); }
 408 };
 409 }   // namespace detail
 410
 411 /// \defgroup PackedChannelReferenceModel packed_channel_reference
 412 /// \ingroup ChannelModel
 413 /// \brief Represents a reference proxy to a channel operating over a bit range whose offset is fixed at compile time. Models ChannelConcept
 414 /// Example:
 415 /// \code
 416 /// // Reference to a 2-bit channel starting at bit 1 (i.e. the second bit)
 417 /// using bits2_1_ref_t = packed_channel_reference<uint16_t,1,2,true> const;
 418 ///
 419 /// uint16_t data=0;
 420 /// bits2_1_ref_t channel_ref(&data);
 421 /// channel_ref = channel_traits<bits2_1_ref_t>::max_value();   // == 3
 422 /// assert(data == 6);                                          // == 3<<1 == 6
 423 /// \endcode
 424
 425 /// \tparam BitField A type that holds the bits of the pixel from which the channel is referenced. Typically an integral type, like std::uint16_t
 426 /// \tparam Defines the sequence of bits in the data value that contain the channel
 427 /// \tparam true if the reference is mutable
 428 template <typename BitField, int FirstBit, int NumBits, bool IsMutable>
 429 class packed_channel_reference;
 430
 431 /// \tparam A type that holds the bits of the pixel from which the channel is referenced. Typically an integral type, like std::uint16_t
 432 /// \tparam Defines the sequence of bits in the data value that contain the channel
 433 /// \tparam true if the reference is mutable
 434 template <typename BitField, int NumBits, bool IsMutable>
 435 class packed_dynamic_channel_reference;
 436
 437 /// \ingroup PackedChannelReferenceModel
 438 /// \brief A constant subbyte channel reference whose bit offset is fixed at compile time. Models ChannelConcept
 439 template <typename BitField, int FirstBit, int NumBits>
 440 class packed_channel_reference<BitField, FirstBit, NumBits, false>
 441     : public detail::packed_channel_reference_base
 442         <
 443             packed_channel_reference<BitField, FirstBit, NumBits, false>,
 444             BitField,
 445             NumBits,
 446             false
 447         >
 448 {
 449     using parent_t = detail::packed_channel_reference_base
 450         <
 451             packed_channel_reference<BitField, FirstBit, NumBits, false>,
 452             BitField,
 453             NumBits,
 454             false
 455         >;
 456
 457     friend class packed_channel_reference<BitField, FirstBit, NumBits, true>;
 458
 459     static const BitField channel_mask = static_cast<BitField>(parent_t::max_val) << FirstBit;
 460
 461     void operator=(packed_channel_reference const&);
 462 public:
 463     using const_reference = packed_channel_reference<BitField,FirstBit,NumBits,false> const;
 464     using mutable_reference = packed_channel_reference<BitField,FirstBit,NumBits,true> const;
 465     using integer_t = typename parent_t::integer_t;
 466
 467     explicit packed_channel_reference(const void* data_ptr) : parent_t(data_ptr) {}
 468     packed_channel_reference(const packed_channel_reference& ref) : parent_t(ref._data_ptr) {}
 469     packed_channel_reference(const mutable_reference& ref) : parent_t(ref._data_ptr) {}
 470
 471     unsigned first_bit() const { return FirstBit; }
 472
 473     integer_t get() const { return integer_t((this->get_data()&channel_mask) >> FirstBit); }
 474 };
 475
 476 /// \ingroup PackedChannelReferenceModel
 477 /// \brief A mutable subbyte channel reference whose bit offset is fixed at compile time. Models ChannelConcept
 478 template <typename BitField, int FirstBit, int NumBits>
 479 class packed_channel_reference<BitField,FirstBit,NumBits,true>
 480    : public detail::packed_channel_reference_base<packed_channel_reference<BitField,FirstBit,NumBits,true>,BitField,NumBits,true>
 481 {
 482     using parent_t = detail::packed_channel_reference_base<packed_channel_reference<BitField,FirstBit,NumBits,true>,BitField,NumBits,true>;
 483     friend class packed_channel_reference<BitField,FirstBit,NumBits,false>;
 484
 485     static const BitField channel_mask = static_cast< BitField >( parent_t::max_val ) << FirstBit;
 486
 487 public:
 488     using const_reference = packed_channel_reference<BitField,FirstBit,NumBits,false> const;
 489     using mutable_reference = packed_channel_reference<BitField,FirstBit,NumBits,true> const;
 490     using integer_t = typename parent_t::integer_t;
 491
 492     explicit packed_channel_reference(void* data_ptr) : parent_t(data_ptr) {}
 493     packed_channel_reference(const packed_channel_reference& ref) : parent_t(ref._data_ptr) {}
 494
 495     packed_channel_reference const& operator=(integer_t value) const
 496     {
 497         BOOST_ASSERT(value <= parent_t::max_val);
 498         set_unsafe(value);
 499         return *this;
 500     }
 501
 502     const packed_channel_reference& operator=(const mutable_reference& ref) const { set_from_reference(ref.get_data()); return *this; }
 503     const packed_channel_reference& operator=(const const_reference&   ref) const { set_from_reference(ref.get_data()); return *this; }
 504
 505     template <bool Mutable1>
 506     const packed_channel_reference& operator=(const packed_dynamic_channel_reference<BitField,NumBits,Mutable1>& ref) const { set_unsafe(ref.get()); return *this; }
 507
 508     unsigned first_bit() const { return FirstBit; }
 509
 510     integer_t get()                  const { return integer_t((this->get_data()&channel_mask) >> FirstBit); }
 511     void set_unsafe(integer_t value) const { this->set_data((this->get_data() & ~channel_mask) | (( static_cast< BitField >( value )<<FirstBit))); }
 512 private:
 513     void set_from_reference(const BitField& other_bits) const { this->set_data((this->get_data() & ~channel_mask) | (other_bits & channel_mask)); }
 514 };
 515
 516 }}  // namespace boost::gil
 517
 518 namespace std {
 519 // We are forced to define swap inside std namespace because on some platforms (Visual Studio 8) STL calls swap qualified.
 520 // swap with 'left bias':
 521 // - swap between proxy and anything
 522 // - swap between value type and proxy
 523 // - swap between proxy and proxy
 524
 525 /// \ingroup PackedChannelReferenceModel
 526 /// \brief swap for packed_channel_reference
 527 template <typename BF, int FB, int NB, bool M, typename R>
 528 inline
 529 void swap(boost::gil::packed_channel_reference<BF, FB, NB, M> const x, R& y)
 530 {
 531     boost::gil::swap_proxy
 532     <
 533         typename boost::gil::packed_channel_reference<BF, FB, NB, M>::value_type
 534     >(x, y);
 535 }
 536
 537
 538 /// \ingroup PackedChannelReferenceModel
 539 /// \brief swap for packed_channel_reference
 540 template <typename BF, int FB, int NB, bool M>
 541 inline
 542 void swap(
 543     typename boost::gil::packed_channel_reference<BF, FB, NB, M>::value_type& x,
 544     boost::gil::packed_channel_reference<BF, FB, NB, M> const y)
 545 {
 546     boost::gil::swap_proxy
 547     <
 548         typename boost::gil::packed_channel_reference<BF, FB, NB, M>::value_type
 549     >(x,y);
 550 }
 551
 552 /// \ingroup PackedChannelReferenceModel
 553 /// \brief swap for packed_channel_reference
 554 template <typename BF, int FB, int NB, bool M> inline
 555 void swap(
 556     boost::gil::packed_channel_reference<BF, FB, NB, M> const x,
 557     boost::gil::packed_channel_reference<BF, FB, NB, M> const y)
 558 {
 559     boost::gil::swap_proxy
 560     <
 561         typename boost::gil::packed_channel_reference<BF, FB, NB, M>::value_type
 562     >(x,y);
 563 }
 564
 565 }   // namespace std
 566
 567 namespace boost { namespace gil {
 568
 569 /// \defgroup PackedChannelDynamicReferenceModel packed_dynamic_channel_reference
 570 /// \ingroup ChannelModel
 571 /// \brief Represents a reference proxy to a channel operating over a bit range whose offset is specified at run time. Models ChannelConcept
 572 ///
 573 /// Example:
 574 /// \code
 575 /// // Reference to a 2-bit channel whose offset is specified at construction time
 576 /// using bits2_dynamic_ref_t = packed_dynamic_channel_reference<uint8_t,2,true> const;
 577 ///
 578 /// uint16_t data=0;
 579 /// bits2_dynamic_ref_t channel_ref(&data,1);
 580 /// channel_ref = channel_traits<bits2_dynamic_ref_t>::max_value();     // == 3
 581 /// assert(data == 6);                                                  // == (3<<1) == 6
 582 /// \endcode
 583
 584 /// \brief Models a constant subbyte channel reference whose bit offset is a runtime parameter. Models ChannelConcept
 585 ///        Same as packed_channel_reference, except that the offset is a runtime parameter
 586 /// \ingroup PackedChannelDynamicReferenceModel
 587 template <typename BitField, int NumBits>
 588 class packed_dynamic_channel_reference<BitField,NumBits,false>
 589    : public detail::packed_channel_reference_base<packed_dynamic_channel_reference<BitField,NumBits,false>,BitField,NumBits,false>
 590 {
 591     using parent_t = detail::packed_channel_reference_base<packed_dynamic_channel_reference<BitField,NumBits,false>,BitField,NumBits,false>;
 592     friend class packed_dynamic_channel_reference<BitField,NumBits,true>;
 593
 594     unsigned _first_bit;     // 0..7
 595
 596     void operator=(const packed_dynamic_channel_reference&);
 597 public:
 598     using const_reference = packed_dynamic_channel_reference<BitField,NumBits,false> const;
 599     using mutable_reference = packed_dynamic_channel_reference<BitField,NumBits,true> const;
 600     using integer_t = typename parent_t::integer_t;
 601
 602     packed_dynamic_channel_reference(const void* data_ptr, unsigned first_bit) : parent_t(data_ptr), _first_bit(first_bit) {}
 603     packed_dynamic_channel_reference(const const_reference&   ref) : parent_t(ref._data_ptr), _first_bit(ref._first_bit) {}
 604     packed_dynamic_channel_reference(const mutable_reference& ref) : parent_t(ref._data_ptr), _first_bit(ref._first_bit) {}
 605
 606     unsigned first_bit() const { return _first_bit; }
 607
 608     integer_t get() const {
 609         const BitField channel_mask = static_cast< integer_t >( parent_t::max_val ) <<_first_bit;
 610         return static_cast< integer_t >(( this->get_data()&channel_mask ) >> _first_bit );
 611     }
 612 };
 613
 614 /// \brief Models a mutable subbyte channel reference whose bit offset is a runtime parameter. Models ChannelConcept
 615 ///        Same as packed_channel_reference, except that the offset is a runtime parameter
 616 /// \ingroup PackedChannelDynamicReferenceModel
 617 template <typename BitField, int NumBits>
 618 class packed_dynamic_channel_reference<BitField,NumBits,true>
 619    : public detail::packed_channel_reference_base<packed_dynamic_channel_reference<BitField,NumBits,true>,BitField,NumBits,true>
 620 {
 621     using parent_t = detail::packed_channel_reference_base<packed_dynamic_channel_reference<BitField,NumBits,true>,BitField,NumBits,true>;
 622     friend class packed_dynamic_channel_reference<BitField,NumBits,false>;
 623
 624     unsigned _first_bit;
 625
 626 public:
 627     using const_reference = packed_dynamic_channel_reference<BitField,NumBits,false> const;
 628     using mutable_reference = packed_dynamic_channel_reference<BitField,NumBits,true> const;
 629     using integer_t = typename parent_t::integer_t;
 630
 631     packed_dynamic_channel_reference(void* data_ptr, unsigned first_bit) : parent_t(data_ptr), _first_bit(first_bit) {}
 632     packed_dynamic_channel_reference(const packed_dynamic_channel_reference& ref) : parent_t(ref._data_ptr), _first_bit(ref._first_bit) {}
 633
 634     packed_dynamic_channel_reference const& operator=(integer_t value) const
 635     {
 636         BOOST_ASSERT(value <= parent_t::max_val);
 637         set_unsafe(value);
 638         return *this;
 639     }
 640
 641     const packed_dynamic_channel_reference& operator=(const mutable_reference& ref) const {  set_unsafe(ref.get()); return *this; }
 642     const packed_dynamic_channel_reference& operator=(const const_reference&   ref) const {  set_unsafe(ref.get()); return *this; }
 643
 644     template <typename BitField1, int FirstBit1, bool Mutable1>
 645     const packed_dynamic_channel_reference& operator=(const packed_channel_reference<BitField1, FirstBit1, NumBits, Mutable1>& ref) const
 646         {  set_unsafe(ref.get()); return *this; }
 647
 648     unsigned first_bit() const { return _first_bit; }
 649
 650     integer_t get() const {
 651         const BitField channel_mask = static_cast< integer_t >( parent_t::max_val ) << _first_bit;
 652         return static_cast< integer_t >(( this->get_data()&channel_mask ) >> _first_bit );
 653     }
 654
 655     void set_unsafe(integer_t value) const {
 656         const BitField channel_mask = static_cast< integer_t >( parent_t::max_val ) << _first_bit;
 657         this->set_data((this->get_data() & ~channel_mask) | value<<_first_bit);
 658     }
 659 };
 660 } }  // namespace boost::gil
 661
 662 namespace std {
 663 // We are forced to define swap inside std namespace because on some platforms (Visual Studio 8) STL calls swap qualified.
 664 // swap with 'left bias':
 665 // - swap between proxy and anything
 666 // - swap between value type and proxy
 667 // - swap between proxy and proxy
 668
 669
 670 /// \ingroup PackedChannelDynamicReferenceModel
 671 /// \brief swap for packed_dynamic_channel_reference
 672 template <typename BF, int NB, bool M, typename R> inline
 673 void swap(const boost::gil::packed_dynamic_channel_reference<BF,NB,M> x, R& y) {
 674     boost::gil::swap_proxy<typename boost::gil::packed_dynamic_channel_reference<BF,NB,M>::value_type>(x,y);
 675 }
 676
 677
 678 /// \ingroup PackedChannelDynamicReferenceModel
 679 /// \brief swap for packed_dynamic_channel_reference
 680 template <typename BF, int NB, bool M> inline
 681 void swap(typename boost::gil::packed_dynamic_channel_reference<BF,NB,M>::value_type& x, const boost::gil::packed_dynamic_channel_reference<BF,NB,M> y) {
 682     boost::gil::swap_proxy<typename boost::gil::packed_dynamic_channel_reference<BF,NB,M>::value_type>(x,y);
 683 }
 684
 685 /// \ingroup PackedChannelDynamicReferenceModel
 686 /// \brief swap for packed_dynamic_channel_reference
 687 template <typename BF, int NB, bool M> inline
 688 void swap(const boost::gil::packed_dynamic_channel_reference<BF,NB,M> x, const boost::gil::packed_dynamic_channel_reference<BF,NB,M> y) {
 689     boost::gil::swap_proxy<typename boost::gil::packed_dynamic_channel_reference<BF,NB,M>::value_type>(x,y);
 690 }
 691 }   // namespace std
 692
 693 // \brief Determines the fundamental type which may be used, e.g., to cast from larger to smaller channel types.
 694 namespace boost { namespace gil {
 695 template <typename T>
 696 struct base_channel_type_impl { using type = T; };
 697
 698 template <int N>
 699 struct base_channel_type_impl<packed_channel_value<N> >
 700 { using type = typename packed_channel_value<N>::integer_t; };
 701
 702 template <typename B, int F, int N, bool M>
 703 struct base_channel_type_impl<packed_channel_reference<B, F, N, M> >
 704 {
 705     using type = typename packed_channel_reference<B,F,N,M>::integer_t;
 706 };
 707
 708 template <typename B, int N, bool M>
 709 struct base_channel_type_impl<packed_dynamic_channel_reference<B, N, M> >
 710 {
 711     using type = typename packed_dynamic_channel_reference<B,N,M>::integer_t;
 712 };
 713
 714 template <typename ChannelValue, typename MinV, typename MaxV>
 715 struct base_channel_type_impl<scoped_channel_value<ChannelValue, MinV, MaxV> >
 716 { using type = ChannelValue; };
 717
 718 template <typename T>
 719 struct base_channel_type : base_channel_type_impl<typename std::remove_cv<T>::type> {};
 720
 721 }} //namespace boost::gil
 722
 723 #endif