boost/gil/bit_aligned_pixel_reference.hpp

   1 //
   2 // Copyright 2005-2007 Adobe Systems Incorporated
   3 // Copyright 2019 Mateusz Loskot <mateusz at loskot dot net>
   4 //
   5 // Distributed under the Boost Software License, Version 1.0
   6 // See accompanying file LICENSE_1_0.txt or copy at
   7 // http://www.boost.org/LICENSE_1_0.txt
   8 //
   9 #ifndef BOOST_GIL_BIT_ALIGNED_PIXEL_REFERENCE_HPP
  10 #define BOOST_GIL_BIT_ALIGNED_PIXEL_REFERENCE_HPP
  11
  12 #include <boost/gil/pixel.hpp>
  13 #include <boost/gil/channel.hpp>
  14 #include <boost/gil/detail/mp11.hpp>
  15
  16 #include <boost/assert.hpp>
  17 #include <boost/config.hpp>
  18
  19 #include <functional>
  20 #include <type_traits>
  21
  22 namespace boost { namespace gil {
  23
  24 /// A model of a heterogeneous pixel that is not byte aligned.
  25 /// Examples are bitmap (1-bit pixels) or 6-bit RGB (222).
  26
  27 /////////////////////////////
  28 //  bit_range
  29 //
  30 //  Represents a range of bits that can span multiple consecutive bytes. The range has a size fixed at compile time, but the offset is specified at run time.
  31 /////////////////////////////
  32
  33 template <int RangeSize, bool IsMutable>
  34 class bit_range {
  35 public:
  36     using byte_t = mp11::mp_if_c<IsMutable, unsigned char, unsigned char const>;
  37     using difference_type = std::ptrdiff_t;
  38     template <int RS, bool M> friend class bit_range;
  39 private:
  40     byte_t* _current_byte;   // the starting byte of the bit range
  41     int     _bit_offset;     // offset from the beginning of the current byte. 0<=_bit_offset<=7
  42
  43 public:
  44     bit_range() : _current_byte(nullptr), _bit_offset(0) {}
  45     bit_range(byte_t* current_byte, int bit_offset)
  46         : _current_byte(current_byte)
  47         , _bit_offset(bit_offset)
  48     {
  49         BOOST_ASSERT(bit_offset >= 0 && bit_offset < 8);
  50     }
  51
  52     bit_range(const bit_range& br) : _current_byte(br._current_byte), _bit_offset(br._bit_offset) {}
  53     template <bool M> bit_range(const bit_range<RangeSize,M>& br) : _current_byte(br._current_byte), _bit_offset(br._bit_offset) {}
  54
  55     bit_range& operator=(const bit_range& br) { _current_byte = br._current_byte; _bit_offset=br._bit_offset; return *this; }
  56     bool operator==(const bit_range& br) const { return  _current_byte==br._current_byte && _bit_offset==br._bit_offset; }
  57
  58     bit_range& operator++() {
  59         _current_byte += (_bit_offset+RangeSize) / 8;
  60         _bit_offset    = (_bit_offset+RangeSize) % 8;
  61         return *this;
  62     }
  63     bit_range& operator--() { bit_advance(-RangeSize); return *this; }
  64
  65     void bit_advance(difference_type num_bits) {
  66         int new_offset = int(_bit_offset+num_bits);
  67         _current_byte += new_offset / 8;
  68         _bit_offset    = new_offset % 8;
  69         if (_bit_offset<0) {
  70             _bit_offset+=8;
  71             --_current_byte;
  72         }
  73     }
  74     difference_type bit_distance_to(const bit_range& b) const {
  75         return (b.current_byte() - current_byte())*8 + b.bit_offset()-bit_offset();
  76     }
  77     byte_t* current_byte() const { return _current_byte; }
  78     int     bit_offset()   const { return _bit_offset; }
  79 };
  80
  81 /// \defgroup ColorBaseModelNonAlignedPixel bit_aligned_pixel_reference
  82 /// \ingroup ColorBaseModel
  83 /// \brief A heterogeneous color base representing pixel that may not be byte aligned, i.e. it may correspond to a bit range that does not start/end at a byte boundary. Models ColorBaseConcept.
  84 ///
  85 /// \defgroup PixelModelNonAlignedPixel bit_aligned_pixel_reference
  86 /// \ingroup PixelModel
  87 /// \brief A heterogeneous pixel reference used to represent non-byte-aligned pixels. Models PixelConcept
  88 ///
  89 /// Example:
  90 /// \code
  91 /// unsigned char data=0;
  92 ///
  93 /// // A mutable reference to a 6-bit BGR pixel in "123" format (1 bit for red, 2 bits for green, 3 bits for blue)
  94 /// using rgb123_ref_t = bit_aligned_pixel_reference<unsigned char, mp11::mp_list_c<int,1,2,3>, rgb_layout_t, true> const;
  95 ///
  96 /// // create the pixel reference at bit offset 2
  97 /// // (i.e. red = [2], green = [3,4], blue = [5,6,7] bits)
  98 /// rgb123_ref_t ref(&data, 2);
  99 /// get_color(ref, red_t()) = 1;
 100 /// assert(data == 0x04);
 101 /// get_color(ref, green_t()) = 3;
 102 /// assert(data == 0x1C);
 103 /// get_color(ref, blue_t()) = 7;
 104 /// assert(data == 0xFC);
 105 /// \endcode
 106 ///
 107 /// \ingroup ColorBaseModelNonAlignedPixel PixelModelNonAlignedPixel PixelBasedModel
 108 /// \brief Heterogeneous pixel reference corresponding to non-byte-aligned bit range. Models ColorBaseConcept, PixelConcept, PixelBasedConcept
 109 ///
 110 /// \tparam BitField
 111 /// \tparam ChannelBitSizes Boost.MP11-compatible list of integral types defining the number of bits for each channel. For example, for 565RGB, mp_list_c<int,5,6,5>
 112 /// \tparam Layout
 113 /// \tparam IsMutable
 114 template <typename BitField, typename ChannelBitSizes, typename Layout, bool IsMutable>
 115 struct bit_aligned_pixel_reference
 116 {
 117     static constexpr int bit_size =
 118             mp11::mp_fold
 119             <
 120                 ChannelBitSizes,
 121                 std::integral_constant<int, 0>,
 122                 mp11::mp_plus
 123             >::value;
 124
 125     using bit_range_t = boost::gil::bit_range<bit_size,IsMutable>;
 126     using bitfield_t = BitField;
 127     using data_ptr_t = mp11::mp_if_c<IsMutable, unsigned char*, const unsigned char*>;
 128
 129     using layout_t = Layout;
 130
 131     using value_type = typename packed_pixel_type<bitfield_t,ChannelBitSizes,Layout>::type;
 132     using reference = const bit_aligned_pixel_reference<BitField, ChannelBitSizes, Layout, IsMutable>;
 133     using const_reference = bit_aligned_pixel_reference<BitField,ChannelBitSizes,Layout,false> const;
 134
 135     static constexpr bool is_mutable = IsMutable;
 136
 137     bit_aligned_pixel_reference(){}
 138     bit_aligned_pixel_reference(data_ptr_t data_ptr, int bit_offset)   : _bit_range(data_ptr, bit_offset) {}
 139     explicit bit_aligned_pixel_reference(const bit_range_t& bit_range) : _bit_range(bit_range) {}
 140     template <bool IsMutable2> bit_aligned_pixel_reference(const bit_aligned_pixel_reference<BitField,ChannelBitSizes,Layout,IsMutable2>& p) : _bit_range(p._bit_range) {}
 141
 142     // Grayscale references can be constructed from the channel reference
 143     explicit bit_aligned_pixel_reference(typename kth_element_type<bit_aligned_pixel_reference,0>::type const channel0)
 144         : _bit_range(static_cast<data_ptr_t>(&channel0), channel0.first_bit())
 145     {
 146         static_assert(num_channels<bit_aligned_pixel_reference>::value == 1, "");
 147     }
 148
 149     // Construct from another compatible pixel type
 150     bit_aligned_pixel_reference(bit_aligned_pixel_reference const& p)
 151         : _bit_range(p._bit_range) {}
 152
 153     // TODO: Why p by non-const reference?
 154     template <typename BF, typename CR>
 155     bit_aligned_pixel_reference(packed_pixel<BF, CR, Layout>& p)
 156         : _bit_range(static_cast<data_ptr_t>(&gil::at_c<0>(p)), gil::at_c<0>(p).first_bit())
 157     {
 158         check_compatible<packed_pixel<BF, CR, Layout>>();
 159     }
 160
 161     auto operator=(bit_aligned_pixel_reference const& p) const
 162         -> bit_aligned_pixel_reference const&
 163     {
 164         static_copy(p, *this);
 165         return *this;
 166     }
 167
 168     template <typename P>
 169     auto operator=(P const& p) const -> bit_aligned_pixel_reference const&
 170     {
 171         assign(p, is_pixel<P>());
 172         return *this;
 173     }
 174
 175     template <typename P>
 176     bool operator==(P const& p) const
 177     {
 178         return equal(p, is_pixel<P>());
 179     }
 180
 181     template <typename P>
 182     bool operator!=(P const& p) const { return !(*this==p); }
 183
 184     auto operator->() const -> bit_aligned_pixel_reference const* { return this; }
 185
 186     bit_range_t const& bit_range() const { return _bit_range; }
 187
 188 private:
 189     mutable bit_range_t _bit_range;
 190     template <typename B, typename C, typename L, bool M> friend struct bit_aligned_pixel_reference;
 191
 192     template <typename Pixel> static void check_compatible() { gil_function_requires<PixelsCompatibleConcept<Pixel,bit_aligned_pixel_reference> >(); }
 193
 194     template <typename Pixel>
 195     void assign(Pixel const& p, std::true_type) const
 196     {
 197         check_compatible<Pixel>();
 198         static_copy(p, *this);
 199     }
 200
 201     template <typename Pixel>
 202     bool equal(Pixel const& p, std::true_type) const
 203     {
 204         check_compatible<Pixel>();
 205         return static_equal(*this, p);
 206     }
 207
 208 private:
 209     static void check_gray()
 210     {
 211         static_assert(std::is_same<typename Layout::color_space_t, gray_t>::value, "");
 212     }
 213
 214     template <typename Channel>
 215     void assign(Channel const& channel, std::false_type) const
 216     {
 217         check_gray();
 218         gil::at_c<0>(*this) = channel;
 219     }
 220
 221     template <typename Channel>
 222     bool equal (Channel const& channel, std::false_type) const
 223     {
 224         check_gray();
 225         return gil::at_c<0>(*this) == channel;
 226     }
 227 };
 228
 229 /////////////////////////////
 230 //  ColorBasedConcept
 231 /////////////////////////////
 232
 233 template <typename BitField, typename ChannelBitSizes, typename L, bool IsMutable, int K>
 234 struct kth_element_type
 235 <
 236     bit_aligned_pixel_reference<BitField, ChannelBitSizes, L, IsMutable>,
 237     K
 238 >
 239 {
 240     using type = packed_dynamic_channel_reference
 241         <
 242             BitField,
 243             mp11::mp_at_c<ChannelBitSizes, K>::value,
 244             IsMutable
 245         > const;
 246 };
 247
 248 template <typename B, typename C, typename L, bool M, int K>
 249 struct kth_element_reference_type<bit_aligned_pixel_reference<B,C,L,M>, K>
 250     : public kth_element_type<bit_aligned_pixel_reference<B,C,L,M>, K> {};
 251
 252 template <typename B, typename C, typename L, bool M, int K>
 253 struct kth_element_const_reference_type<bit_aligned_pixel_reference<B,C,L,M>, K>
 254     : public kth_element_type<bit_aligned_pixel_reference<B,C,L,M>, K> {};
 255
 256 namespace detail {
 257
 258 // returns sum of IntegralVector[0] ... IntegralVector[K-1]
 259 template <typename IntegralVector, int K>
 260 struct sum_k
 261     : mp11::mp_plus
 262         <
 263             sum_k<IntegralVector, K - 1>,
 264             typename mp11::mp_at_c<IntegralVector, K - 1>::type
 265         >
 266 {};
 267
 268 template <typename IntegralVector>
 269 struct sum_k<IntegralVector, 0> : std::integral_constant<int, 0> {};
 270
 271 } // namespace detail
 272
 273 // at_c required by MutableColorBaseConcept
 274 template <int K, typename BitField, typename ChannelBitSizes, typename L, bool IsMutable>
 275 inline
 276 auto at_c(const bit_aligned_pixel_reference<BitField, ChannelBitSizes, L, IsMutable>& p)
 277     -> typename kth_element_reference_type<bit_aligned_pixel_reference<BitField, ChannelBitSizes, L, IsMutable>, K>::type
 278 {
 279     using pixel_t = bit_aligned_pixel_reference<BitField, ChannelBitSizes, L, IsMutable>;
 280     using channel_t = typename kth_element_reference_type<pixel_t, K>::type;
 281     using bit_range_t = typename pixel_t::bit_range_t;
 282
 283     bit_range_t bit_range(p.bit_range());
 284     bit_range.bit_advance(detail::sum_k<ChannelBitSizes, K>::value);
 285
 286     return channel_t(bit_range.current_byte(), bit_range.bit_offset());
 287 }
 288
 289 /////////////////////////////
 290 //  PixelConcept
 291 /////////////////////////////
 292
 293 /// Metafunction predicate that flags bit_aligned_pixel_reference as a model of PixelConcept. Required by PixelConcept
 294 template <typename B, typename C, typename L, bool M>
 295 struct is_pixel<bit_aligned_pixel_reference<B, C, L, M> > : std::true_type {};
 296
 297 /////////////////////////////
 298 //  PixelBasedConcept
 299 /////////////////////////////
 300
 301 template <typename B, typename C, typename L, bool M>
 302 struct color_space_type<bit_aligned_pixel_reference<B, C, L, M>>
 303 {
 304     using type = typename L::color_space_t;
 305 };
 306
 307 template <typename B, typename C, typename L, bool M>
 308 struct channel_mapping_type<bit_aligned_pixel_reference<B, C, L, M>>
 309 {
 310     using type = typename L::channel_mapping_t;
 311 };
 312
 313 template <typename B, typename C, typename L, bool M>
 314 struct is_planar<bit_aligned_pixel_reference<B, C, L, M>> : std::false_type {};
 315
 316 /////////////////////////////
 317 //  pixel_reference_type
 318 /////////////////////////////
 319
 320 // Constructs a homogeneous bit_aligned_pixel_reference given a channel reference
 321 template <typename BitField, int NumBits, typename Layout>
 322 struct pixel_reference_type
 323     <
 324         packed_dynamic_channel_reference<BitField, NumBits, false> const,
 325         Layout, false, false
 326     >
 327 {
 328 private:
 329     using channel_bit_sizes_t = mp11::mp_repeat
 330         <
 331             mp11::mp_list<std::integral_constant<unsigned, NumBits>>,
 332             mp11::mp_size<typename Layout::color_space_t>
 333         >;
 334
 335 public:
 336     using type =
 337         bit_aligned_pixel_reference<BitField, channel_bit_sizes_t, Layout, false>;
 338 };
 339
 340 // Same but for the mutable case. We cannot combine the mutable
 341 // and read-only cases because this triggers ambiguity
 342 template <typename BitField, int NumBits, typename Layout>
 343 struct pixel_reference_type
 344     <
 345         packed_dynamic_channel_reference<BitField, NumBits, true> const,
 346         Layout, false, true
 347     >
 348 {
 349 private:
 350     using channel_bit_sizes_t = mp11::mp_repeat
 351         <
 352             mp11::mp_list<std::integral_constant<unsigned, NumBits>>,
 353             mp11::mp_size<typename Layout::color_space_t>
 354         >;
 355
 356 public:
 357     using type = bit_aligned_pixel_reference<BitField, channel_bit_sizes_t, Layout, true>;
 358 };
 359
 360 } }  // namespace boost::gil
 361
 362 namespace std {
 363
 364 // We are forced to define swap inside std namespace because on some platforms (Visual Studio 8) STL calls swap qualified.
 365 // swap with 'left bias':
 366 // - swap between proxy and anything
 367 // - swap between value type and proxy
 368 // - swap between proxy and proxy
 369 // Having three overloads allows us to swap between different (but compatible) models of PixelConcept
 370
 371 template <typename B, typename C, typename L, typename R> inline
 372 void swap(const boost::gil::bit_aligned_pixel_reference<B,C,L,true> x, R& y) {
 373     boost::gil::swap_proxy<typename boost::gil::bit_aligned_pixel_reference<B,C,L,true>::value_type>(x,y);
 374 }
 375
 376
 377 template <typename B, typename C, typename L> inline
 378 void swap(typename boost::gil::bit_aligned_pixel_reference<B,C,L,true>::value_type& x, const boost::gil::bit_aligned_pixel_reference<B,C,L,true> y) {
 379     boost::gil::swap_proxy<typename boost::gil::bit_aligned_pixel_reference<B,C,L,true>::value_type>(x,y);
 380 }
 381
 382
 383 template <typename B, typename C, typename L> inline
 384 void swap(const boost::gil::bit_aligned_pixel_reference<B,C,L,true> x, const boost::gil::bit_aligned_pixel_reference<B,C,L,true> y) {
 385     boost::gil::swap_proxy<typename boost::gil::bit_aligned_pixel_reference<B,C,L,true>::value_type>(x,y);
 386 }
 387
 388 } // namespace std
 389
 390 #endif