picoquant_t3.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_t2.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 T3 formats (pqt3_picoharp300_event and basic_pqt3_event) use
// matching member names for static polymorphism. This allows
// decode_pqt3<PQT3Event> to handle 3 different formats with the same code.

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

    static constexpr i32 nsync_overflow_period = 65536;

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

    [[nodiscard]] constexpr auto dtime() const noexcept -> u16np {
        return read_u16le_at<2>(std::span(bytes)) & 0x0fff_u16np;
    }

    [[nodiscard]] constexpr auto nsync() const noexcept -> u16np {
        return read_u16le_at<0>(std::span(bytes));
    }

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

    [[nodiscard]] constexpr auto is_nsync_overflow() const noexcept -> bool {
        return is_special() && dtime() == 0_u16np;
    }

    [[nodiscard]] static constexpr auto nsync_overflow_count() noexcept
        -> u16np {
        return 1_u16np;
    }

    [[nodiscard]] constexpr auto is_external_marker() const noexcept -> bool {
        // Vendor docs do not specifically say markers are 4 bits in PicoHarp
        // 300 T3, but they are in a 4-bit field in T2, and in
        // HydraHarp/Generic T2/T3 the marker bits explicitly range 1-15. Let's
        // just behave consistently here and check the upper limit.
        return is_special() && dtime() > 0_u16np && dtime() <= 15_u16np;
    }

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

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

    static constexpr auto make_nsync_overflow() noexcept
        -> pqt3_picoharp300_event {
        return make_from_fields(15_u8np, 0_u16np, 0_u16np);
    }

    static constexpr auto make_external_marker(u16np nsync, u8np marker_bits)
        -> pqt3_picoharp300_event {
        if (marker_bits == 0_u8np)
            throw std::invalid_argument(
                "pqt3_picoharp300_event marker_bits must not be zero");
        return make_from_fields(15_u8np, u16np(marker_bits & 0x0f_u8np),
                                nsync);
    }

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

    friend auto operator<<(std::ostream &stream,
                           pqt3_picoharp300_event const &event)
        -> std::ostream & {
        return stream << "pqt3_picoharp(channel="
                      << unsigned(event.channel().value())
                      << ", dtime=" << event.dtime()
                      << ", nsync=" << event.nsync() << ")";
    }
 
  private:
    static constexpr auto make_from_fields(u8np channel, u16np dtime,
                                           u16np nsync)
        -> pqt3_picoharp300_event {
        return pqt3_picoharp300_event{{
            std::byte(u8np(nsync).value()),
            std::byte(u8np(nsync >> 8).value()),
            std::byte(u8np(dtime).value()),
            std::byte(
                ((channel << 4) | (u8np(dtime >> 8) & 0x0f_u8np)).value()),
        }};
    }
};

template <bool IsNSyncOverflowAlwaysSingle> struct basic_pqt3_event {
    std::array<std::byte, 4> bytes;

    static constexpr i32 nsync_overflow_period = 1024;

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

    [[nodiscard]] constexpr auto dtime() const noexcept -> u16np {
        auto const lo6 = u16np(read_u8_at<1>(std::span(bytes))) >> 2;
        auto const mid8 = u16np(read_u8_at<2>(std::span(bytes)));
        auto const hi1 = u16np(read_u8_at<3>(std::span(bytes))) & 1_u16np;
        return lo6 | (mid8 << 6) | (hi1 << 14);
    }

    [[nodiscard]] constexpr auto nsync() const noexcept -> u16np {
        return read_u16le_at<0>(std::span(bytes)) & 0x03ff_u16np;
    }

    [[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_nsync_overflow() const noexcept -> bool {
        return is_special() && channel() == 63_u8np;
    }

    [[nodiscard]] constexpr auto nsync_overflow_count() const noexcept
        -> u16np {
        if (IsNSyncOverflowAlwaysSingle)
            return 1_u16np;
        return nsync();
    }

    [[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(u16np nsync, u8np channel,
                                          u16np dtime) -> basic_pqt3_event {
        return make_from_fields(false, channel, dtime, nsync);
    }

    static constexpr auto make_nsync_overflow(u16np count)
        -> basic_pqt3_event {
        static_assert(
            not IsNSyncOverflowAlwaysSingle,
            "multiple nsync overflow is not available in HydraHarp V1 format");
        return make_from_fields(true, 63_u8np, 0_u16np, count);
    }

    static constexpr auto make_nsync_overflow() noexcept -> basic_pqt3_event {
        return make_from_fields(true, 63_u8np, 0_u16np, 1_u16np);
    }

    static constexpr auto make_external_marker(u16np nsync, u8np marker_bits)
        -> basic_pqt3_event {
        return make_from_fields(true, marker_bits, 0_u16np, nsync);
    }

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

    friend auto operator<<(std::ostream &stream, basic_pqt3_event const &event)
        -> std::ostream & {
        static constexpr auto version = IsNSyncOverflowAlwaysSingle ? 1 : 2;
        return stream << "pqt3_hydraharpv" << version
                      << "(special=" << event.is_special()
                      << ", channel=" << unsigned(event.channel().value())
                      << ", dtime=" << event.dtime()
                      << ", nsync=" << event.nsync() << ")";
    }
 
  private:
    static constexpr auto make_from_fields(bool special, u8np channel,
                                           u16np dtime, u16np nsync)
        -> basic_pqt3_event {
        return basic_pqt3_event{{
            std::byte(u8np(nsync).value()),
            std::byte(
                (u8np(dtime << 2) | (u8np(nsync >> 8) & 0x03_u8np)).value()),
            std::byte(u8np(dtime >> 6).value()),
            std::byte(((u8np(u8(special)) << 7) |
                       ((channel & 0x3f_u8np) << 1) |
                       (u8np(dtime >> 14) & 0x01_u8np))
                          .value()),
        }};
    }
};

using pqt3_hydraharpv1_event = basic_pqt3_event<true>;

using pqt3_generic_event = basic_pqt3_event<false>;
 
namespace internal {
 
// Common implementation for decode_pqt3_*.
// PQT3Event is the binary record event class.
template <typename DataTypes, typename PQT3Event, typename Downstream>
class decode_pqt3 {
    static_assert(processor<Downstream, time_reached_event<DataTypes>,
                            time_correlated_detection_event<DataTypes>,
                            marker_event<DataTypes>, warning_event>);
 
    // 16-bit abstime would overflow so fast that we just prohibit. 32-bit 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));
    static_assert(std::in_range<typename DataTypes::difftime_type>(32767));
 
    using abstime_type = typename DataTypes::abstime_type;
 
    abstime_type nsync_base = 0;
 
    Downstream downstream;
 
    LIBTCSPC_NOINLINE void issue_warning(char const *message) {
        downstream.handle(warning_event{message});
    }
 
  public:
    explicit decode_pqt3(Downstream downstream)
        : downstream(std::move(downstream)) {}
 
    [[nodiscard]] auto introspect_node() const -> processor_info {
        return processor_info(this, "decode_pqt3");
    }
 
    [[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>, PQT3Event>
    void handle(Event &&event) {
        if (event.is_nsync_overflow()) {
            nsync_base += abstime_type(PQT3Event::nsync_overflow_period) *
                          event.nsync_overflow_count().value();
            return downstream.handle(
                time_reached_event<DataTypes>{nsync_base});
        }
 
        abstime_type const nsync = nsync_base + event.nsync().value();
 
        if (not event.is_special()) {
            downstream.handle(time_correlated_detection_event<DataTypes>{
                nsync, event.channel().value(), event.dtime().value()});
        } else if (event.is_external_marker()) {
            for_each_set_bit(u32np(event.external_marker_bits()), [&](int b) {
                downstream.handle(marker_event<DataTypes>{nsync, b});
            });
        } else {
            issue_warning("invalid special event encountered");
        }
    }
 
    template <typename Event>
        requires(
            not std::convertible_to<std::remove_cvref_t<Event>, PQT3Event> 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_pqt3_picoharp300(Downstream downstream) {
    return internal::decode_pqt3<DataTypes, pqt3_picoharp300_event,
                                 Downstream>(std::move(downstream));
}

template <typename DataTypes = default_data_types, typename Downstream>
auto decode_pqt3_hydraharpv1(Downstream downstream) {
    return internal::decode_pqt3<DataTypes, pqt3_hydraharpv1_event,
                                 Downstream>(std::move(downstream));
}

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