Add PcloudAmbienceStencil, LG1PcloudAmbienceStencil

These two classes represent our first foray into stencil
construction. One of them standardizes PcloudAmbience stencils
across all stimbuffs, and the other specifies the internal
memory constraints and requirements for a LivoxGen1 device's
stencils.

include/user/pcloudAmbienceStencil.h

@@ -0,0 +1,38 @@
+#ifndef _PCLOUD_AMBIENCE_STENCIL_H
+#define _PCLOUD_AMBIENCE_STENCIL_H
+
+#include <cstdint>
+#include <cstddef>
+#include <user/stencil.h>
+
+namespace smo {
+namespace stim_buff {
+
+/**
+ * PcloudAmbienceStencil represents stencils for point cloud ambience data.
+ * This is a base class for device-specific implementations.
+ */
+class PcloudAmbienceStencil
+:	public smo::cologex::Stencil
+{
+public:
+	typedef uint32_t PcloudAmbienceStimulusValue;
+
+	/**
+	 * RangeDescriptor describes a contiguous range of body spots for
+	 * point cloud ambience stencils.
+	 */
+	struct RangeDescriptor : public Stencil::RangeDescriptor
+	{
+		uint32_t bodySpot;
+		size_t nContiguousSpots;
+	};
+
+	PcloudAmbienceStencil() = default;
+	virtual ~PcloudAmbienceStencil() = default;
+};
+
+} // namespace stim_buff
+} // namespace smo
+
+#endif // _PCLOUD_AMBIENCE_STENCIL_H

include/user/stencil.h

@@ -1,9 +1,7 @@
 #ifndef _STENCIL_H
 #define _STENCIL_H
 
-#include <vector>
-#include <memory>
-#include <user/stimFrame.h>
+#include <cstddef>
 #include <mentalEntity.h>
 
 namespace smo {
@@ -31,31 +29,24 @@ namespace cologex {
 class Stencil
 {
 public:
-	/**
-	 * Constructor that takes a shared_ptr to StimFrame and produces a completed
-	 * Stencil. The Stencil scans the StimFrame and efficiently allocates
-	 * internal structures to describe the stencil ranges.
-	 *
-	 * @param frame Shared pointer to the StimFrame to analyze
-	 * @param threshold The threshold value for determining relevant data
+	/**	EXPLANATION:
+	 * This is used by smo and stimbufflibs to describe the range of bodyspot
+	 * descriptors in a stencil. Each descriptor describes a contiguous range of
+	 * body spots whose values exceed the intrin threshold for the intrin being
+	 * reported. Or in the case of a stored cologex/idea, it describes
+	 * contiguous body spots in the perceptual reference data, which may
+	 * eventually be whittled/collapsed down from implicative data into
+	 * structural data.
 	 */
-	Stencil(
-		const std::shared_ptr<stim_buff::StimFrame> &frame,
-		const uint32_t threshold)
-	: frame(frame), threshold(threshold)
-	{}
+	struct RangeDescriptor
+	{
+	};
+
+	Stencil() = default;
 	virtual ~Stencil() = default;
 
 	/**
-	 * Pure virtual method for derived classes to implement their specific
-	 * threshold analysis logic. Returns true if there are values above threshold,
-	 * false otherwise.
-	 */
-	virtual bool analyzeFrame() = 0;
-
-	/**
-	 * Stencil is constructed from a StimFrame. If the input StimFrame had no
-	 * values above threshold, then the Stencil will have no data.
+	 * Returns true if the Stencil has data, false otherwise.
 	 */
 	virtual bool hasData() const = 0;
 	operator bool() const { return hasData(); }
@@ -66,15 +57,13 @@ public:
 	// Return true if the offset is relevant, false otherwise
 	virtual bool isRelevant(size_t offset) const = 0;
 
+	virtual size_t getNRangeDescriptors() const = 0;
+
 	/**
-	 * Build internal stencil metadata from the shared_ptr member to describe
-	 * the range of StimFrame values that are relevant.
+	 * Build internal stencil metadata to describe the range of values that
+	 * are relevant.
 	 */
 	virtual bool buildStencilMetadata() = 0;
-
-protected:
-	uint32_t threshold;
-	std::shared_ptr<stim_buff::StimFrame> frame;
 };
 
 } // namespace cologex

stimBuffApis/livoxGen1/CMakeLists.txt

@@ -15,6 +15,7 @@ if(ENABLE_STIMBUFFAPI_livoxGen1)
 	add_library(livoxGen1 SHARED
 		livoxGen1.cpp
 		pcloudStimulusProducer.cpp
+		lg1PcloudAmbienceStencil.cpp
 		ioUringAssemblyEngine.cpp
 		openClCollatingAndMeshingEngine.cpp
 		openClKernels.cl.S

stimBuffApis/livoxGen1/lg1PcloudAmbienceStencil.cpp

@@ -0,0 +1,19 @@
+#include "lg1PcloudAmbienceStencil.h"
+#include <unistd.h>
+
+namespace smo {
+namespace stim_buff {
+
+// Common IOEngineConstraints for LG1 ambience stencil StagingBuffer
+// (used for both input and output constraints)
+const StagingBuffer::IOEngineConstraints
+LG1PcloudAmbienceStencil::stencilBufferConstraints(
+	// slotStartAlignmentByteVal, slotPadToNBytes.
+	sizeof(void*),
+	sizeof(PcloudAmbienceStencil::RangeDescriptor),
+	// frameStartAlignmentByteVal, framePadToNBytes.
+	static_cast<size_t>(sysconf(_SC_PAGE_SIZE)),
+	static_cast<size_t>(sysconf(_SC_PAGE_SIZE)));
+
+} // namespace stim_buff
+} // namespace smo

stimBuffApis/livoxGen1/lg1PcloudAmbienceStencil.h

@@ -0,0 +1,45 @@
+#ifndef _LG1_PCLOUD_AMBIENCE_STENCIL_H
+#define _LG1_PCLOUD_AMBIENCE_STENCIL_H
+
+#include "livoxGen1.h"
+#include <user/pcloudAmbienceStencil.h>
+#include <user/stagingBuffer.h>
+#include <unistd.h>
+
+namespace smo {
+namespace stim_buff {
+
+/**
+ * LG1PcloudAmbienceStencil represents Livox Gen1-specific stencils for
+ * ambience data. The StagingBuffer is sized to handle the worst-case scenario
+ * where every ambience body spot requires its own descriptor
+ * (nDgramsPerFrame slots).
+ */
+class LG1PcloudAmbienceStencil
+:	public PcloudAmbienceStencil
+{
+public:
+	// Common IOEngineConstraints for stencil buffer (used for both input and output)
+	static const StagingBuffer::IOEngineConstraints stencilBufferConstraints;
+
+	/**
+	 * Constructor
+	 * @param nDgramsPerFrame Number of datagrams per frame, used to size the
+	 *        stencil buffer for worst-case scenario (one descriptor per dgram)
+	 */
+	explicit LG1PcloudAmbienceStencil(size_t nDgramsPerFrame)
+	:	PcloudAmbienceStencil(),
+	stencilBuffer(
+		stencilBufferConstraints,  // Input constraints
+		stencilBufferConstraints,  // Output constraints (same as input)
+		nDgramsPerFrame)
+	{}
+
+public:
+	StagingBuffer stencilBuffer;
+};
+
+} // namespace stim_buff
+} // namespace smo
+
+#endif // _LG1_PCLOUD_AMBIENCE_STENCIL_H

stimBuffApis/livoxGen1/pcloudStimulusProducer.cpp

@@ -9,7 +9,9 @@
 #include <asynchronousLoop.h>
 #include <user/stimulusFrame.h>
 #include <user/frameAssemblyDesc.h>
+#include <user/pcloudAmbienceStencil.h>
 #include <livoxProto1/device.h>
+#include "livoxGen1.h"
 #include "pcloudStimulusProducer.h"
 
 namespace smo {
@@ -56,7 +58,7 @@ static StagingBuffer::IOEngineConstraints openClAmbienceInputConstraints(
 	// slotStartAlignmentByteVal (page alignment)
 	static_cast<size_t>(sysconf(_SC_PAGE_SIZE)),
 	// slotPadToNBytes: This is dynamically calculated based on the return mode.
-	sizeof(uint32_t),
+	sizeof(PcloudAmbienceStencil::PcloudAmbienceStimulusValue),
 	// frameStartAlignmentByteVal (page alignment)
 	static_cast<size_t>(sysconf(_SC_PAGE_SIZE)),
 	// framePadToNBytes (pointer size)