salmanoff/stimBuffApis/livoxGen1/pcloudAmbienceStimulusBuffer.h

#ifndef _LIVOX_GEN1_PCLOUD_AMBIENCE_STIMULUS_BUFFER_H
#define _LIVOX_GEN1_PCLOUD_AMBIENCE_STIMULUS_BUFFER_H

#include <cstddef>
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <user/deviceAttachmentSpec.h>
#include <user/intrin.h>
#include <user/intrinThresholdParams.h>
#include <user/stagingBuffer.h>
#include <user/stimulusBuffer.h>
#include "pcloudAmbienceQualeIfaceApi.h"

namespace smo {
namespace stim_buff {

class StimulusProducer;

inline intrin::IntrinConfig parseAmbienceIntrinConfigFromParams(
	std::string_view intrinKind,
	const std::vector<std::pair<std::string, std::string>>& params,
	size_t nDgramsPerFrame)
{
	intrin::validateIntrinSegmentParams(intrinKind, params);

	const auto threshold = intrin::parseOptionalThresholdParam(
		params,
		intrin::kIntrinInterestPcNames,
		intrin::kIntrinInterestThrNames,
		/*defaultValue=*/0,
		/*defaultUnit=*/intrin::ThresholdUnit::Absolute);

	return intrin::IntrinConfig{
		.percentage =
			threshold.unit == intrin::ThresholdUnit::Percentage
				? static_cast<uint32_t>(threshold.value)
				: 0U,
		.threshold = intrin::resolveThresholdValue(
			threshold, nDgramsPerFrame),
	};
}

/**
 * Sensory PcloudAmbience buffer: per-dgram ambience floats. A DAP spec may
 * optionally attach a postrin(...) and/or a negtrin(...) specifier to this
 * qualeIfaceApi; when present, interest thresholds from those specifiers and
 * passband-count comparators from this spec's own qualeIfaceApi params are
 * combined to decide when an intrin event should fire.
 *
 * Convention: the postrin pipeline pairs with passband-count-lt-val (a sparse
 * ambient scene being "too good, stay here"); the negtrin pipeline pairs with
 * passband-count-gt-val (a dense ambient scene being "unbearably much, get
 * away"). Both comparators may be specified simultaneously on this qualeIface.
 */
class PcloudAmbienceStimulusBuffer
:	public StimulusBuffer
{
public:
	explicit PcloudAmbienceStimulusBuffer(
		StimulusProducer& parent,
		const std::shared_ptr<device::DeviceAttachmentSpec>& deviceAttachmentSpec,
		int histbuffMs,
		const StagingBuffer::IOEngineConstraints& inputEngineConstraints,
		const StagingBuffer::IOEngineConstraints& outputEngineConstraints,
		const SmoCallbacks& callbacks,
		cl_mem_flags flags,
		size_t nDgramsPerFrame_)
	:	StimulusBuffer(
			parent, deviceAttachmentSpec, histbuffMs,
			inputEngineConstraints, outputEngineConstraints,
			callbacks, flags),
	nDgramsPerFrame(nDgramsPerFrame_)
	{
		intrin::validateNoIntrinParamsOnQualeIface(
			deviceAttachmentSpec->qualeIfaceApi,
			deviceAttachmentSpec->qualeIfaceApiParams);

		const auto passbandComparators =
			parsePcloudAmbiencePassbandComparators(deviceAttachmentSpec);
		passbandCountLtComparator = passbandComparators.lt;
		passbandCountGtComparator = passbandComparators.gt;

		if (!deviceAttachmentSpec->postrin.empty())
		{
			postrinInterestConfig = parseAmbienceIntrinConfigFromParams(
				"postrin",
				deviceAttachmentSpec->postrinParams,
				nDgramsPerFrame_);

			if (!passbandCountLtComparator.has_value())
			{
				throw std::runtime_error(
					"pcloudAmbience DAP spec declares a postrin(...) but no "
					"'passband-count-lt-val' on the pcloudAmbience qualeIface "
					"params to feed it.");
			}
		}

		if (!deviceAttachmentSpec->negtrin.empty())
		{
			negtrinInterestConfig = parseAmbienceIntrinConfigFromParams(
				"negtrin",
				deviceAttachmentSpec->negtrinParams,
				nDgramsPerFrame_);

			if (!passbandCountGtComparator.has_value())
			{
				throw std::runtime_error(
					"pcloudAmbience DAP spec declares a negtrin(...) but no "
					"'passband-count-gt-val' on the pcloudAmbience qualeIface "
					"params to feed it.");
			}
		}
	}

	~PcloudAmbienceStimulusBuffer() = default;

	PcloudAmbienceStimulusBuffer(const PcloudAmbienceStimulusBuffer&) = delete;
	PcloudAmbienceStimulusBuffer& operator=(
		const PcloudAmbienceStimulusBuffer&) = delete;
	PcloudAmbienceStimulusBuffer(PcloudAmbienceStimulusBuffer&&) = delete;
	PcloudAmbienceStimulusBuffer& operator=(
		PcloudAmbienceStimulusBuffer&&) = delete;

	bool shouldTriggerPostrinEvent(uint32_t ambiencePassbandCount) const
	{
		if (!postrinInterestConfig.has_value()) { return false; }
		return ambiencePassbandCount >= postrinInterestConfig->threshold;
	}

	bool shouldTriggerNegtrinEvent(uint32_t ambiencePassbandCount) const
	{
		if (!negtrinInterestConfig.has_value()) { return false; }
		return ambiencePassbandCount >= negtrinInterestConfig->threshold;
	}

public:
	size_t nDgramsPerFrame;
	std::optional<intrin::IntrinConfig> postrinInterestConfig;
	std::optional<intrin::IntrinConfig> negtrinInterestConfig;
	std::optional<ParamComparator> passbandCountLtComparator;
	std::optional<ParamComparator> passbandCountGtComparator;
};

} // namespace stim_buff
} // namespace smo

#endif // _LIVOX_GEN1_PCLOUD_AMBIENCE_STIMULUS_BUFFER_H