detray/utils/bit_encoder.hpp

0001 // This file is part of the ACTS project.
0002 //
0003 // Copyright (C) 2016 CERN for the benefit of the ACTS project
0004 //
0005 // This Source Code Form is subject to the terms of the Mozilla Public
0006 // License, v. 2.0. If a copy of the MPL was not distributed with this
0007 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
0008
0009 #pragma once
0010
0011 // Project include(s)
0012 #include "detray/definitions/detail/qualifiers.hpp"
0013
0014 // System include(s)
0015 #include <cstdint>
0016 #include <type_traits>
0017
0018 namespace detray::detail {
0019
0020 /// @brief Sets masked bits to a given value.
0021 ///
0022 /// Given a mask and an input value, the corresponding bits are set on a target
0023 /// value. Used e.g. in the surface identifier.
0024 ///
0025 /// @see
0026 /// https://github.com/acts-project/acts/blob/main/Core/include/Acts/Geometry/GeometryIdentifier.hpp
0027 template <typename value_t = std::uint64_t>
0028 class bit_encoder {
0029  public:
0030   bit_encoder() = delete;
0031
0032   /// Check whether the set @param v encodes valid values according to the
0033   /// given masks (@tparam head and @tparam tail)
0034   template <value_t... masks>
0035   DETRAY_HOST_DEVICE static constexpr bool is_invalid(value_t v) noexcept {
0036     // All bits set to one in the range of a given mask defined as invalid
0037     return (((v & masks) == masks) || ...);
0038   }
0039
0040   /// @returns the masked bits from the encoded value as value of the same
0041   /// type.
0042   template <value_t mask>
0043     requires(mask != static_cast<value_t>(0))
0044   DETRAY_HOST_DEVICE static constexpr value_t get_bits(
0045       const value_t v) noexcept {
0046     // Use integral constant to enforce compile time evaluation of shift
0047     return (v & mask) >> extract_shift(mask);
0048   }
0049
0050   /// Set the masked bits to id in the encoded value.
0051   template <value_t mask>
0052     requires(mask != static_cast<value_t>(0))
0053   DETRAY_HOST_DEVICE static constexpr void set_bits(value_t& v,
0054                                                     const value_t id) noexcept {
0055     // Use integral constant to enforce compile time evaluation of shift
0056     v = (v & ~mask) | ((id << extract_shift(mask)) & mask);
0057
0058     // Make sure, the value 'id' can be safely encoded with the bits
0059     // specified by 'mask' (unless it is an invalid value which has all bits
0060     // set to 1)
0061     assert(((id == ~static_cast<value_t>(0)) ||
0062             (id == static_cast<value_t>(~static_cast<unsigned int>(0))) ||
0063             (get_bits<mask>(v) == id)) &&
0064            "Not enough bits in mask to encode value");
0065   }
0066
0067  private:
0068   /// Extract the bit shift necessary to access the masked values.
0069   ///
0070   /// @note undefined behaviour for mask == 0 which we should not have.
0071   DETRAY_HOST_DEVICE
0072   static constexpr int extract_shift(value_t mask) noexcept {
0073     return __builtin_ctzll(mask);
0074   }
0075 };
0076
0077 }  // namespace detray::detail