Lg1: Implement both light|darkAmbience stimBuffs & their production

We now produce both light and dark ambience stimframes into
stimbuffs for the LivoxGen1 lidar devices.

stimBuffApis/livoxGen1/openClCollatingAndMeshingEngine.h

@@ -21,12 +21,24 @@
 #include <user/frameAssemblyDesc.h>
 #include <user/compute.h>
 #include <user/senseApiDesc.h>
+#include "pcloudAmbienceQualeIfaceApi.h"
 
 #define OCLCOLLMESH_ENGN_FINALIZE_DELAY_MS 1
 
 namespace smo {
 namespace stim_buff {
 
+/* One "job" per attached ambience stimbuff: the StimulusFrame to write the
+ * uint32 passband count into, and the comparator to apply to the per-slot
+ * averages the collate kernel staged into averageIntensityBuffer. A job is
+ * only constructed when its corresponding ambience stimbuff is attached.
+ */
+struct AmbienceProductionDesc
+{
+	std::reference_wrapper<StimulusFrame> frame;
+	ParamComparator comparator;
+};
+
 // Custom deleters for OpenCL handles
 struct ClProgramDeleter
 {
@@ -80,7 +92,8 @@ public:
 	void compactCollateAndMeshFrameReq(
 		sscl::AsynchronousLoop& asyncLoop, StimulusFrame& stimulusFrame,
 		std::optional<std::reference_wrapper<StimulusFrame>> intensityStimFrame,
-		std::optional<std::reference_wrapper<StimulusFrame>> ambienceStimFrame,
+		std::optional<AmbienceProductionDesc> lightAmbienceProductionDesc,
+		std::optional<AmbienceProductionDesc> darkAmbienceProductionDesc,
 		sscl::Callback<compactCollateAndMeshFrameReqCbFn> callback);
 
 private:
@@ -93,16 +106,25 @@ private:
 		compactKernelCbFn callback);
 	bool startCollateKernel(
 		std::optional<std::reference_wrapper<StimulusFrame>> intensityStimFrame,
-		std::optional<std::reference_wrapper<StimulusFrame>> ambienceStimFrame,
+		bool anyAmbienceAttached,
 		collateKernelCbFn callback);
 
 	void compactKernelComplete(bool isFinalizing=false);
 	void collateKernelComplete(
 		std::optional<std::reference_wrapper<StimulusFrame>> intensityStimFrame,
-		std::optional<std::reference_wrapper<StimulusFrame>> ambienceStimFrame,
+		bool anyAmbienceAttached,
 		bool isFinalizing=false);
 	bool stop();
 
+	/* Apply `comparator` to the nSucceeded per-slot averages the collate
+	 * kernel wrote into averageIntensityBuffer, and write the resulting
+	 * uint32 passband count as the single stimspot of `ambienceFrame`.
+	 */
+	void produceAmbienceStimulusFrame(
+		StimulusFrame& ambienceFrame,
+		const ParamComparator& comparator,
+		uint32_t nSucceeded);
+
 public:
 	// Get kernel execution durations in milliseconds
 	std::chrono::milliseconds getCompactKernelDuration() const;
@@ -121,9 +143,11 @@ private:
 	// OpenCL buffers (managed by ComputeManager)
 	std::shared_ptr<smo::compute::ClBuffer> clAssemblyBufferClBuffer;
 	std::shared_ptr<smo::compute::ClBuffer> clCollationBufferClBuffer;
+	std::shared_ptr<smo::compute::ClBuffer> clAverageIntensityBufferClBuffer;
 	// Cached cl_mem handles for the device we're using
 	cl_mem clAssemblyBuffer;
 	cl_mem clCollationBuffer;
+	cl_mem clAverageIntensityBuffer;
 
 	// State tracking
 	sscl::SpinLock shouldAcceptRequestsLock;
@@ -138,9 +162,12 @@ private:
 	size_t assemblyBufferSize;
 	void* collationBufferPtr;
 	size_t collationBufferSize;
+	void* averageIntensityBufferPtr;
+	size_t averageIntensityBufferSize;
 	// Mapped buffer pointers (for zero-copy synchronization)
 	void* mappedAssemblyBuffer;
 	void* mappedCollationBuffer;
+	void* mappedAverageIntensityBuffer;
 
 	// Frame descriptor (cached from setup)
 	std::shared_ptr<FrameAssemblyDesc> frameAssemblyDesc;
@@ -174,7 +201,7 @@ private:
 		StagingBuffer& assemblyBuff, uint32_t nSucceeded);
 	bool setupCollateDgramsArgs(
 		std::optional<std::reference_wrapper<StimulusFrame>> intensityStimFrame,
-		std::optional<std::reference_wrapper<StimulusFrame>> ambienceStimFrame);
+		bool anyAmbienceAttached);
 
 	// Generic buffer mapping/unmapping for zero-copy synchronization
 	bool mapBuffer(
@@ -186,6 +213,8 @@ private:
 	bool unmapAssemblyBuffer();
 	bool mapCollationBuffer(cl_map_flags mapFlags = CL_MAP_READ);
 	bool unmapCollationBuffer();
+	bool mapAverageIntensityBuffer(cl_map_flags mapFlags = CL_MAP_READ);
+	bool unmapAverageIntensityBuffer();
 
 	// Forward declaration for continuation class
 	class CompactCollateAndMeshFrameReq;