Remove public per-feature struct header; caller defines its own struct matching the documented composite-option layout

The SDK must not ship any feature-specific typed struct for composite
options - only the generic rs2_composite_option_id enum and the
rs2_set/get_composite_option pair are public. Deleted
include/librealsense2/h/rs_hkr_temporal_filter_dpp.h and its include from
rs.h; the HKR Temporal Filter DPP wire layout (4 fields, 16 bytes) is now
documented as a comment on RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP in
rs_composite_option.h instead of as a type.

Each caller of the generic API independently defines its own local struct
matching that documented layout: d500_depth_sensor uses a private
hkr_temporal_filter_dpp_wire_layout (file-scope, d500-device.cpp) only to
compute the control's registered wire size; the realsense-viewer panel and
the fake-transport mock example each define their own separate local copies
to cast the raw bytes. None of these three structs are shared types - they
just happen to agree on layout by convention, exactly like a real
app would have to.

Rebuilt realsense2, realsense-viewer, and the mock example (0 errors) and
reconfirmed round-trip correctness and the exactly-one-set_xu/one-get_xu
atomicity guarantee through the caller-owned-struct contract.

Author: Evgeni Raikhel

common/device-model.cpp

@@ -29,6 +29,25 @@ using namespace rs400;
 using rsutils::json;
 using namespace rs2::sw_update;
 
+namespace {
+
+// PROTOTYPE / DEMO: this viewer's OWN local struct matching the wire layout documented as a
+// comment on RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP in
+// include/librealsense2/h/rs_composite_option.h. The SDK ships no public type for composite
+// options - every caller (this viewer, the mock example under examples/) independently
+// defines its own copy of this struct matching the documented byte layout.
+#pragma pack( push, 1 )
+struct hkr_temporal_filter_dpp_layout
+{
+    int32_t enabled;           // 0 = Off, 1 = On
+    float smooth_alpha;        // range [0,1], default 0.4, step 0.01
+    int32_t smooth_delta;      // range [1,100], default 20, step 1
+    int32_t persistency_index; // range [0,8], default 3, step 1
+};
+#pragma pack( pop )
+
+}  // namespace
+
 namespace rs2
 {
     // RAII guard pairing BeginDisabled/EndDisabled: keeps them balanced even if an exception is
@@ -2776,10 +2795,12 @@ namespace rs2
                 // same way as other per-sensor extension features in this loop, e.g.
                 // depth_sensor above). Goes through the GENERIC rs2::composite_option_sensor
                 // get_composite_option/set_composite_option entry points, keyed by
-                // RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP - this viewer code is the only
-                // place that knows to cast the raw bytes to/from rs2_temporal_filter_dpp_config.
-                // All fields are sent together in ONE atomic UVC transaction when "Apply" is
-                // clicked - never as separate per-field option writes.
+                // RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP. The SDK ships no struct for
+                // this - this viewer casts the raw bytes to/from its own local
+                // hkr_temporal_filter_dpp_layout (defined above), matching the layout
+                // documented as a comment on the enumerator. All fields are sent together in
+                // ONE atomic UVC transaction when "Apply" is clicked - never as separate
+                // per-field option writes.
                 if (sub->s->is<rs2::composite_option_sensor>())
                 {
                     auto composite_sensor = sub->s->as<rs2::composite_option_sensor>();
@@ -2792,10 +2813,10 @@ namespace rs2
                             if (!sub->temporal_filter_dpp_populated)
                             {
                                 auto bytes = composite_sensor.get_composite_option(RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP);
-                                if (bytes.size() != sizeof(rs2_temporal_filter_dpp_config))
+                                if (bytes.size() != sizeof(hkr_temporal_filter_dpp_layout))
                                     throw std::runtime_error("HKR Temporal Filter DPP: unexpected payload size from get_composite_option");
 
-                                rs2_temporal_filter_dpp_config cfg{};
+                                hkr_temporal_filter_dpp_layout cfg{};
                                 memcpy(&cfg, bytes.data(), sizeof(cfg));
                                 sub->temporal_filter_dpp_enabled = cfg.enabled;
                                 sub->temporal_filter_dpp_smooth_alpha = cfg.smooth_alpha;
@@ -2821,7 +2842,7 @@ namespace rs2
                             label = rsutils::string::from() << "Send##temporal_filter_dpp_send" << id;
                             if (ImGui::Button(label.c_str()))
                             {
-                                rs2_temporal_filter_dpp_config cfg{};
+                                hkr_temporal_filter_dpp_layout cfg{};
                                 cfg.enabled = sub->temporal_filter_dpp_enabled;
                                 cfg.smooth_alpha = sub->temporal_filter_dpp_smooth_alpha;
                                 cfg.smooth_delta = sub->temporal_filter_dpp_smooth_delta;

examples/hkr-temporal-filter-dpp-mock/rs-hkr-temporal-filter-dpp-mock.cpp

@@ -13,10 +13,14 @@
 // What this proves:
 //   1. Round-trip correctness: a payload sent via set_raw(void*, size) comes back
 //      byte-identical in the SDK-allocated vector returned by get_raw(), once memcpy'd into
-//      the caller's typed struct (rs2_temporal_filter_dpp_config) - exactly the contract of
-//      the real rs2_set_composite_option(data, data_size) / rs2_get_composite_option()
-//      (which returns an rs2_raw_data_buffer, since the caller has no generic way to know an
-//      arbitrary option_id's wire size in advance - mirrors rs2_get_safety_preset).
+//      THIS EXAMPLE'S OWN local struct (hkr_temporal_filter_dpp_layout, below) - exactly the
+//      contract of the real rs2_set_composite_option(data, data_size) /
+//      rs2_get_composite_option() (which returns an rs2_raw_data_buffer, since the caller has
+//      no generic way to know an arbitrary option_id's wire size in advance - mirrors
+//      rs2_get_safety_preset). The SDK ships NO typed struct for composite options: this
+//      example defines its own struct matching the byte layout documented as a comment on
+//      RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP in
+//      include/librealsense2/h/rs_composite_option.h.
 //   2. Atomicity: set_raw() performs EXACTLY ONE set_xu() call, and get_raw() performs
 //      EXACTLY ONE get_xu() call - i.e. the whole payload always travels as a single UVC
 //      transaction, never as separate per-field writes/reads. This is the non-negotiable
@@ -28,9 +32,9 @@
 // - only the transport (platform::uvc_device) is faked.
 
 #include <src/ds/structured-xu-control.h>
-#include <librealsense2/h/rs_hkr_temporal_filter_dpp.h>
 
 #include <cassert>
+#include <cstdint>
 #include <cstring>
 #include <iostream>
 #include <stdexcept>
@@ -39,6 +43,20 @@ using namespace librealsense;
 
 namespace {
 
+// This example's OWN local struct - NOT an SDK type - matching the wire layout documented as
+// a comment on RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP in rs_composite_option.h. Any
+// real application would define its own copy of this exact struct the same way; the SDK does
+// not provide one.
+#pragma pack( push, 1 )
+struct hkr_temporal_filter_dpp_layout
+{
+    int32_t enabled;           // 0 = Off, 1 = On
+    float smooth_alpha;        // range [0,1], default 0.4, step 0.01
+    int32_t smooth_delta;      // range [1,100], default 20, step 1
+    int32_t persistency_index; // range [0,8], default 3, step 1
+};
+#pragma pack( pop )
+
 // Minimal fake transport standing in for the real UVC backend. Implements just enough of
 // platform::uvc_device to exercise xu_structured_control::get_raw/set_raw. Everything else is
 // unused by this test and throws loudly if ever invoked - this class is test scaffolding
@@ -114,9 +132,9 @@ try
 
     // Generic control, registered for exactly this one composite option's wire size - mirrors
     // how d500_depth_sensor populates its _structured_controls registry.
-    xu_structured_control control( depth_xu, DS5_HKR_TEMPORAL_FILTER_DPP, sizeof( rs2_temporal_filter_dpp_config ) );
+    xu_structured_control control( depth_xu, DS5_HKR_TEMPORAL_FILTER_DPP, sizeof( hkr_temporal_filter_dpp_layout ) );
 
-    rs2_temporal_filter_dpp_config sent{};
+    hkr_temporal_filter_dpp_layout sent{};
     sent.enabled = 1;
     sent.smooth_alpha = 0.4f;
     sent.smooth_delta = 20;
@@ -130,10 +148,10 @@ try
     control.set_raw( dev, &sent, sizeof( sent ) );
 
     std::vector< uint8_t > bytes = control.get_raw( dev );
-    if( bytes.size() != sizeof( rs2_temporal_filter_dpp_config ) )
+    if( bytes.size() != sizeof( hkr_temporal_filter_dpp_layout ) )
         throw std::runtime_error( "get_raw returned an unexpected payload size" );
 
-    rs2_temporal_filter_dpp_config received{};
+    hkr_temporal_filter_dpp_layout received{};
     std::memcpy( &received, bytes.data(), sizeof( received ) );
 
     // 1) Round-trip correctness.

include/librealsense2/h/rs_composite_option.h

@@ -9,13 +9,15 @@
 * rs2_get_composite_option) shared by every composite (multi-field, atomically-exchanged) XU
 * control, keyed by an rs2_composite_option_id. This mirrors Orbbec OrbbecSDK's
 * setStructuredData(OBPropertyID, const void*, uint32_t) / getStructuredData(...) pattern:
-* there is no bespoke named function per feature - adding a new composite option means adding
-* one enumerator here (plus its typed payload struct, e.g. rs2_temporal_filter_dpp_config in
-* rs_hkr_temporal_filter_dpp.h) and registering it internally, NOT adding new public functions.
+* there is no bespoke named function per feature, and - importantly - the SDK does NOT ship a
+* public typed struct per feature either. Adding a new composite option means adding one
+* enumerator here (with its wire layout DOCUMENTED as a comment, not as a type) and
+* registering it internally, NOT adding new public functions or public structs. Callers define
+* their own local struct matching the documented layout for whichever option_id they use.
 *
 * Each call performs EXACTLY ONE UVC control transaction (one set_xu/get_xu round trip): all
-* fields of the option's payload struct travel together, atomically - never as separate
-* per-field writes/reads.
+* fields of the option's payload travel together, atomically - never as separate per-field
+* writes/reads.
 */
 
 #ifndef LIBREALSENSE_RS2_COMPOSITE_OPTION_H
@@ -28,27 +30,40 @@ extern "C" {
 #include "rs_types.h"
 
 /**
-* Identifies which composite option (and therefore which typed payload struct) a
-* rs2_set_composite_option/rs2_get_composite_option call refers to. This enum is the ONLY
+* Identifies which composite option a rs2_set_composite_option/rs2_get_composite_option call
+* refers to. This enum (and the documented byte layout on each enumerator below) is the ONLY
 * per-feature footprint of the generic mechanism - the entry point functions themselves never
-* change.
+* change, and the SDK ships no typed struct for any of these. The caller/app is responsible
+* for defining its own local struct matching the documented layout and casting the raw bytes
+* to/from it.
 */
 typedef enum rs2_composite_option_id
 {
-    RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP, /**< Prototype: HKR/D555 Depth Post-Processing Temporal Filter. Payload: rs2_temporal_filter_dpp_config (see rs_hkr_temporal_filter_dpp.h) */
+    /** Prototype: HKR/D555 Depth Post-Processing Temporal Filter.
+     * Documented wire layout (tightly packed, no padding - all fields are naturally
+     * 4-byte-aligned so no explicit packing pragma is required in the caller's struct),
+     * 16 bytes total, in this exact field order:
+     *   int32_t enabled;             0 = Off, 1 = On
+     *   float   smooth_alpha;        range [0,1], default 0.4, step 0.01
+     *   int32_t smooth_delta;        range [1,100], default 20, step 1
+     *   int32_t persistency_index;   range [0,8], default 3, step 1
+     * The SDK does not define a type for this - define your own local struct matching this
+     * layout and pass &your_struct / sizeof(your_struct) to rs2_set/get_composite_option. */
+    RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP,
     RS2_COMPOSITE_OPTION_COUNT
 } rs2_composite_option_id;
 const char* rs2_composite_option_id_to_string(rs2_composite_option_id id);
 
 /**
 * rs2_set_composite_option - generic composite-option setter.
 * Writes data_size bytes from data to the device in ONE atomic UVC control transaction (one
-* set_xu call). The caller is responsible for knowing which typed struct corresponds to
-* option_id and passing its address + sizeof(...) as data/data_size.
+* set_xu call). The caller is responsible for knowing the documented wire layout for option_id
+* (see rs2_composite_option_id above) and passing a pointer to its own matching struct +
+* sizeof(...) as data/data_size. The SDK does not ship a typed struct for this.
 * \param[in]  sensor       Sensor that exposes the requested composite option
 * \param[in]  option_id    Which composite option to write
-* \param[in]  data         Pointer to the caller's typed payload struct
-* \param[in]  data_size    sizeof(...) of the caller's typed payload struct
+* \param[in]  data         Pointer to the caller's own struct matching the documented layout
+* \param[in]  data_size    sizeof(...) of the caller's struct
 * \param[out] error        If non-null, receives any error that occurs during this call, otherwise, errors are ignored
 */
 void rs2_set_composite_option(const rs2_sensor* sensor, rs2_composite_option_id option_id, const void* data, unsigned int data_size, rs2_error** error);
@@ -64,8 +79,9 @@ void rs2_set_composite_option(const rs2_sensor* sensor, rs2_composite_option_id
 * \param[in]   option_id    Which composite option to read
 * \param[out]  error        If non-null, receives any error that occurs during this call, otherwise, errors are ignored
 * \return                   SDK-allocated buffer holding the option's raw payload bytes; the
-*                            caller casts them to the typed struct that corresponds to option_id
-*                            (e.g. rs2_temporal_filter_dpp_config). Free with rs2_delete_raw_data.
+*                            caller casts them into its own local struct matching the
+*                            documented layout for option_id (see rs2_composite_option_id
+*                            above). Free with rs2_delete_raw_data.
 */
 const rs2_raw_data_buffer* rs2_get_composite_option(const rs2_sensor* sensor, rs2_composite_option_id option_id, rs2_error** error);
 

include/librealsense2/h/rs_hkr_temporal_filter_dpp.h

@@ -44,8 +44,10 @@ namespace rs2
         // Single atomic UVC transaction (one get_xu round trip). The SDK allocates the result
         // (the caller has no generic way to know option_id's wire size in advance) and this
         // wrapper hides the raw rs2_raw_data_buffer/manual-free entirely, returning a plain
-        // std::vector<uint8_t> of the option's raw payload bytes - cast/memcpy them into the
-        // typed struct that corresponds to option_id (e.g. rs2_temporal_filter_dpp_config).
+        // std::vector<uint8_t> of the option's raw payload bytes. The SDK ships no typed
+        // struct for this - cast/memcpy the bytes into your own local struct matching the
+        // layout documented on the corresponding rs2_composite_option_id enumerator (see
+        // rs_composite_option.h).
         std::vector<uint8_t> get_composite_option(rs2_composite_option_id option_id) const
         {
             rs2_error* e = nullptr;

include/librealsense2/hpp/rs_composite_option.hpp

@@ -24,7 +24,6 @@ extern "C" {
 #include "h/rs_sensor.h"
 #include "h/rs_safety_sensor.h"
 #include "h/rs_eth_config.h"
-#include "h/rs_hkr_temporal_filter_dpp.h"
 #include "h/rs_composite_option.h"
 
 #define RS2_API_MAJOR_VERSION    2

include/librealsense2/rs.h

@@ -23,9 +23,11 @@ class composite_option_interface
     virtual ~composite_option_interface() = default;
 
     // Generic dispatch by option id. Each call performs EXACTLY ONE UVC control transaction
-    // (one set_xu/get_xu). The bytes are an opaque blob whose layout is defined by whichever
-    // typed struct corresponds to option_id (e.g. rs2_temporal_filter_dpp_config for
-    // RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP) - the caller is responsible for casting.
+    // (one set_xu/get_xu). The bytes are an opaque blob whose layout is documented as a
+    // comment on the corresponding rs2_composite_option_id enumerator (see
+    // rs_composite_option.h) - the SDK ships no typed struct for it. The caller is
+    // responsible for defining its own local struct matching that documented layout and
+    // casting to/from it.
     //
     // get_composite_option returns a vector sized exactly to that option's known wire size -
     // the caller has no generic way to know that size in advance, so the SDK owns the

src/composite-option-interface.h

@@ -40,6 +40,29 @@ constexpr bool hw_mon_over_xu = true;
 constexpr bool hw_mon_over_xu = false;
 #endif
 
+namespace {
+
+// PROTOTYPE / DEMO: internal-only wire layout for RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP,
+// used ONLY here to compute this control's wire size when registering it below. This is a
+// private implementation detail, NOT a public SDK type - the public API ships no struct for
+// composite options at all (see include/librealsense2/h/rs_composite_option.h, which
+// documents this exact layout as a comment on the enumerator). Callers (realsense-viewer,
+// the mock example) each independently define their own local struct matching that documented
+// layout - this one is not shared with them.
+#pragma pack( push, 1 )
+struct hkr_temporal_filter_dpp_wire_layout
+{
+    int32_t enabled;
+    float smooth_alpha;
+    int32_t smooth_delta;
+    int32_t persistency_index;
+};
+#pragma pack( pop )
+static_assert( sizeof( hkr_temporal_filter_dpp_wire_layout ) == 16,
+               "must match the wire layout documented on RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP in rs_composite_option.h" );
+
+}  // namespace
+
 namespace librealsense
 {
     std::map<uint32_t, rs2_format> d500_depth_fourcc_to_rs2_format = {
@@ -134,7 +157,7 @@ namespace librealsense
         // are fully generic and never change.
         _structured_controls.emplace(
             RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP,
-            xu_structured_control( ds::depth_xu, ds::DS5_HKR_TEMPORAL_FILTER_DPP, sizeof( rs2_temporal_filter_dpp_config ) ) );
+            xu_structured_control( ds::depth_xu, ds::DS5_HKR_TEMPORAL_FILTER_DPP, sizeof( hkr_temporal_filter_dpp_wire_layout ) ) );
     }
 
     // PROTOTYPE / DEMO: generic composite-option dispatch - single atomic UVC transaction (one

src/ds/d500/d500-device.cpp

@@ -23,7 +23,6 @@
 #include <src/embedded-filter-interface.h>
 #include <src/composite-option-interface.h>
 #include <src/ds/structured-xu-control.h>
-#include <librealsense2/h/rs_hkr_temporal_filter_dpp.h>
 
 #include <map>