picoquant_t2.hpp

/*
 * This file is part of libtcspc
 * Copyright 2019-2026 Board of Regents of the University of Wisconsin System
 * SPDX-License-Identifier: MIT
 */
 
#pragma once
 
#include "common.hpp"
#include "core.hpp"
#include "data_types.hpp"
#include "int_arith.hpp"
#include "int_types.hpp"
#include "introspect.hpp"
#include "npint.hpp"
#include "npint_ops.hpp"
#include "processor.hpp"
#include "read_integers.hpp"
#include "time_tagged_events.hpp"
 
#include <array>
#include <cstddef>
#include <ostream>
#include <span>
#include <stdexcept>
#include <type_traits>
#include <utility>
 
// When editing this file, maintain the partial symmetry with picoquant_t3.hpp.
 
namespace tcspc {
 
// PicoQuant raw time tag event ("TTTR") formats are documented in the html
// files contained in this repository:
// https://github.com/PicoQuant/PicoQuant-Time-Tagged-File-Format-Demos
 
// Vendor documentation does not specify, but the 32-bit records are to be
// viewed as little-endian integers when interpreting the documented bit
// locations.
 
// The two T2 formats (pqt2_picoharp300_event and basic_pqt2_event) use
// matching member names for static polymorphism. This allows
// decode_pqt2<PQT2Event> to handle 3 different formats with the same code.

struct pqt2_picoharp300_event {
    std::array<std::byte, 4> bytes;

    static constexpr i32 overflow_period = 210698240;

    [[nodiscard]] constexpr auto channel() const noexcept -> u8np {
        return read_u8_at<3>(std::span(bytes)) >> 4;
    }

    [[nodiscard]] constexpr auto timetag() const noexcept -> u32np {
        return read_u32le_at<0>(std::span(bytes)) & 0x0fff'ffff_u32np;
    }

    [[nodiscard]] constexpr auto external_marker_timetag() const noexcept
        -> u32np {
        // For markers, the low 4 bits of the time tag are used to store the
        // marker bits, giving markers 1/16 the time resolution (the actual
        // time resolution for markers is even lower, in the 10s of ns range).
        // Avoid leaving the marker bits in the timestamp.
        return timetag() & ~0x0f_u32np;
    }

    [[nodiscard]] constexpr auto is_special() const noexcept -> bool {
        return channel() == 15_u8np;
    }

    [[nodiscard]] constexpr auto is_timetag_overflow() const noexcept -> bool {
        return is_special() && (timetag() & 0x0f_u32np) == 0_u32np;
    }

    [[nodiscard]] static constexpr auto timetag_overflow_count() noexcept
        -> u32np {
        return 1_u32np;
    }

    [[nodiscard]] static constexpr auto is_sync_event() noexcept -> bool {
        return false;
    }

    [[nodiscard]] constexpr auto is_external_marker() const noexcept -> bool {
        return is_special() && (timetag() & 0x0f_u32np) != 0_u32np;
    }

    [[nodiscard]] constexpr auto external_marker_bits() const noexcept
        -> u8np {
        return u8np(timetag()) & 0x0f_u8np;
    }

    static constexpr auto make_nonspecial(u32np timetag, u8np channel)
        -> pqt2_picoharp300_event {
        if (channel > 14_u8np)
            throw std::invalid_argument(
                "pqt2_picoharp300_event channel must be in the range 0-14");
        return make_from_fields(channel, timetag);
    }

    static constexpr auto make_timetag_overflow() noexcept
        -> pqt2_picoharp300_event {
        return make_from_fields(15_u8np, 0_u32np);
    }

    static constexpr auto make_external_marker(u32np timetag, u8np marker_bits)
        -> pqt2_picoharp300_event {
        if (marker_bits == 0_u8np)
            throw std::invalid_argument(
                "pqt2_picoharp300_event marker_bits must not be zero");
        return make_from_fields(15_u8np,
                                (timetag & ~0x0f_u32np) |
                                    (u32np(marker_bits) & 0x0f_u32np));
    }

    friend auto operator==(pqt2_picoharp300_event const &lhs,
                           pqt2_picoharp300_event const &rhs) noexcept
        -> bool = default;

    friend auto operator<<(std::ostream &stream,
                           pqt2_picoharp300_event const &event)
        -> std::ostream & {
        return stream << "pqt2_picoharp(channel="
                      << unsigned(event.channel().value())
                      << ", timetag=" << event.timetag() << ")";
    }
 
  private:
    static constexpr auto make_from_fields(u8np channel, u32np timetag)
        -> pqt2_picoharp300_event {
        return pqt2_picoharp300_event{{
            std::byte(u8np(timetag).value()),
            std::byte(u8np(timetag >> 8).value()),
            std::byte(u8np(timetag >> 16).value()),
            std::byte(
                ((channel << 4) | (u8np(timetag >> 24) & 0x0f_u8np)).value()),
        }};
    }
};

template <i32 OverflowPeriod, bool IsOverflowAlwaysSingle>
struct basic_pqt2_event {
    std::array<std::byte, 4> bytes;

    static constexpr i32 overflow_period = OverflowPeriod;

    [[nodiscard]] constexpr auto channel() const noexcept -> u8np {
        return (read_u8_at<3>(std::span(bytes)) & 0x7f_u8np) >> 1;
    }

    [[nodiscard]] constexpr auto timetag() const noexcept -> u32np {
        return read_u32le_at<0>(std::span(bytes)) & 0x01ff'ffff_u32np;
    }

    [[nodiscard]] constexpr auto external_marker_timetag() const noexcept
        -> u32np {
        return timetag();
    }

    [[nodiscard]] constexpr auto is_special() const noexcept -> bool {
        return (read_u8_at<3>(std::span(bytes)) & (1_u8np << 7)) != 0_u8np;
    }

    [[nodiscard]] constexpr auto is_timetag_overflow() const noexcept -> bool {
        return is_special() && channel() == 63_u8np;
    }

    [[nodiscard]] constexpr auto timetag_overflow_count() const noexcept
        -> u32np {
        if (IsOverflowAlwaysSingle)
            return 1_u32np;
        return timetag();
    }

    [[nodiscard]] constexpr auto is_sync_event() const noexcept -> bool {
        return is_special() && channel() == 0_u8np;
    }

    [[nodiscard]] constexpr auto is_external_marker() const noexcept -> bool {
        return is_special() && channel() > 0_u8np && channel() <= 15_u8np;
    }

    [[nodiscard]] constexpr auto external_marker_bits() const noexcept
        -> u8np {
        return channel();
    }

    static constexpr auto make_nonspecial(u32np timetag, u8np channel)
        -> basic_pqt2_event {
        return make_from_fields(false, channel, timetag);
    }

    static constexpr auto make_timetag_overflow(u32np count)
        -> basic_pqt2_event {
        static_assert(
            not IsOverflowAlwaysSingle,
            "multiple time tag overflow is not available in HydraHarp V1 format");
        return make_from_fields(true, 63_u8np, count);
    }

    static constexpr auto make_timetag_overflow() noexcept
        -> basic_pqt2_event {
        return make_from_fields(true, 63_u8np, 1_u32np);
    }

    static constexpr auto make_sync(u32np timetag) noexcept
        -> basic_pqt2_event {
        return make_from_fields(true, 0_u8np, timetag);
    }

    static constexpr auto make_external_marker(u32np timetag, u8np marker_bits)
        -> basic_pqt2_event {
        if (marker_bits == 0_u8np || (marker_bits & ~0x0f_u8np) != 0_u8np)
            throw std::invalid_argument(
                "basic_pqt2_event marker_bits must be in range 1-15");
        return make_from_fields(true, marker_bits & 0x3f_u8np, timetag);
    }

    friend auto operator==(basic_pqt2_event const &lhs,
                           basic_pqt2_event const &rhs) noexcept
        -> bool = default;

    friend auto operator<<(std::ostream &stream, basic_pqt2_event const &event)
        -> std::ostream & {
        static constexpr auto version = IsOverflowAlwaysSingle ? 1 : 2;
        return stream << "pqt2_hydraharpv" << version
                      << "(special=" << event.is_special()
                      << ", channel=" << unsigned(event.channel().value())
                      << ", timetag=" << event.timetag() << ")";
    }
 
  private:
    static constexpr auto make_from_fields(bool special, u8np channel,
                                           u32np timetag) -> basic_pqt2_event {
        return basic_pqt2_event{{
            std::byte(u8np(timetag).value()),
            std::byte(u8np(timetag >> 8).value()),
            std::byte(u8np(timetag >> 16).value()),
            std::byte(((u8np(u8(special)) << 7) |
                       ((channel & 0x3f_u8np) << 1) |
                       (u8np(timetag >> 24) & 0x01_u8np))
                          .value()),
        }};
    }
};

using pqt2_hydraharpv1_event = basic_pqt2_event<33552000, true>;

using pqt2_generic_event = basic_pqt2_event<33554432, false>;
 
namespace internal {
 
// Common implementation for decode_pqt2_*.
// PQT2Event is the binary record event class.
template <typename DataTypes, typename PQT2Event, typename Downstream>
class decode_pqt2 {
    static_assert(processor<Downstream, time_reached_event<DataTypes>,
                            detection_event<DataTypes>,
                            marker_event<DataTypes>, warning_event>);
 
    // 32-bit abstime can work for a few seconds, though 64-bit is recommended.
    static_assert(sizeof(typename DataTypes::abstime_type) >= 4);
    static_assert(std::in_range<typename DataTypes::channel_type>(63));
 
    using abstime_type = typename DataTypes::abstime_type;
 
    abstime_type timetag_base = 0;
 
    Downstream downstream;
 
    LIBTCSPC_NOINLINE void issue_warning(char const *message) {
        downstream.handle(warning_event{message});
    }
 
  public:
    explicit decode_pqt2(Downstream downstream)
        : downstream(std::move(downstream)) {}
 
    [[nodiscard]] auto introspect_node() const -> processor_info {
        return processor_info(this, "decode_pqt2");
    }
 
    [[nodiscard]] auto introspect_graph() const -> processor_graph {
        return downstream.introspect_graph().push_entry_point(this);
    }
 
    template <typename Event>
        requires std::convertible_to<std::remove_cvref_t<Event>, PQT2Event>
    void handle(Event &&event) {
        if (event.is_timetag_overflow()) {
            timetag_base += abstime_type(PQT2Event::overflow_period) *
                            event.timetag_overflow_count().value();
            return downstream.handle(
                time_reached_event<DataTypes>{timetag_base});
        }
 
        // In the case where the overflow period is smaller than one plus
        // the maximum representable time tag (PicoHarp 300 and HydraHarp
        // V1), any invalid time tags will be caught when (externally)
        // checking for monotonicity. So we do not check here.
 
        if (not event.is_special() || event.is_sync_event()) {
            abstime_type const timetag =
                timetag_base + event.timetag().value();
            downstream.handle(detection_event<DataTypes>{
                timetag, event.is_special() ? -1 : event.channel().value()});
        } else if (event.is_external_marker()) {
            abstime_type const timetag =
                timetag_base + event.external_marker_timetag().value();
            for_each_set_bit(u32np(event.external_marker_bits()), [&](int b) {
                downstream.handle(marker_event<DataTypes>{timetag, b});
            });
        } else {
            issue_warning("invalid special event encountered");
        }
    }
 
    template <typename Event>
        requires(
            not std::convertible_to<std::remove_cvref_t<Event>, PQT2Event> and
            handler_for<Downstream, std::remove_cvref_t<Event>>)
    void handle(Event &&event) {
        downstream.handle(std::forward<Event>(event));
    }
 
    void flush() { downstream.flush(); }
};
 
} // namespace internal

template <typename DataTypes = default_data_types, typename Downstream>
auto decode_pqt2_picoharp300(Downstream downstream) {
    return internal::decode_pqt2<DataTypes, pqt2_picoharp300_event,
                                 Downstream>(std::move(downstream));
}

template <typename DataTypes = default_data_types, typename Downstream>
auto decode_pqt2_hydraharpv1(Downstream downstream) {
    return internal::decode_pqt2<DataTypes, pqt2_hydraharpv1_event,
                                 Downstream>(std::move(downstream));
}

template <typename DataTypes = default_data_types, typename Downstream>
auto decode_pqt2_generic(Downstream downstream) {
    return internal::decode_pqt2<DataTypes, pqt2_generic_event, Downstream>(
        std::move(downstream));
}
 
} // namespace tcspc