Add generic composite-option API, proven via HKR Temporal Filter DPP

Introduces a new API surface for multi-parameter XU controls that are
exchanged as one atomic struct in a single UVC transaction, distinct
from the existing single-value rs2_option mechanism:

- C API: rs2_set/get_composite_option, rs2_get_composite_option_range,
  keyed by their own rs2_composite_option_id enum (kept separate from
  rs2_option so composite controls don't collide with the scalar
  option-numbering space), plus metadata queries (description,
  read-only, supported-options enumeration).
- C++ wrapper: rs2::options gains get_composite_option_as<T>()/
  set_composite_option_from<T>()/get_composite_option_range_as<T>(),
  casting the raw payload to/from an application-defined struct that
  matches the documented wire layout - no SDK-side per-feature struct
  header, so adding a new control doesn't require an SDK release.
- composite_xu_option implements the mechanism against a real XU
  transport; options_container gets a second, separate composite-option
  registry alongside its existing scalar one.

HKR Temporal Filter DPP is the first control built on this mechanism,
registered as its own embedded filter (not directly on the sensor),
with a realsense-viewer panel and a fake-transport example proving the
round-trip is atomic. This commit represents the API's final shape;
the design went through several rounds of rework (ownership model,
identity/enum split, casting approach) before landing here.

Author: Evgeni Raikhel

common/device-model.cpp

@@ -5,6 +5,9 @@
 #include <librealsense2/rs.hpp>
 #include <rs-config.h>
 
+#include <algorithm>
+#include <cstring>
+
 #include <third-party/filesystem/glob.h>
 
 #include <imgui.h>
@@ -2871,6 +2874,84 @@ namespace rs2
                     }
                 }
 
+                // PROTOTYPE / DEMO: HKR Temporal Filter DPP "structured API" panel. Only
+                // rendered for a sensor that actually exposes
+                // RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP - composite options are a
+                // completely separate identity space from ordinary rs2_option scalar options, so
+                // support is checked via get_supported_composite_options(), not via
+                // supports()/is<T>()/as<T>() casting. Uses the DIRECT
+                // get_composite_option()/set_composite_option() C++ methods, which call
+                // rs2_get_composite_option/rs2_set_composite_option under the hood - no wrapper
+                // handle type. The SDK ships a public struct for this one prototype control
+                // (rs2_temporal_filter_dpp_config, see rs_hkr_temporal_filter_dpp.h) that this
+                // viewer casts the raw bytes to/from. All fields are sent together in ONE atomic
+                // UVC transaction when "Apply" is clicked - never as separate per-field option
+                // writes.
+                auto supported_composite_options = sub->s->get_supported_composite_options();
+                bool has_temporal_filter_dpp = std::find(supported_composite_options.begin(),
+                                                          supported_composite_options.end(),
+                                                          RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP)
+                                             != supported_composite_options.end();
+                if (has_temporal_filter_dpp)
+                {
+                    label = rsutils::string::from() << "HKR Temporal Filter DPP (prototype)##" << id;
+                    if (ImGui::TreeNode(label.c_str()))
+                    {
+                        try
+                        {
+                            if (!sub->temporal_filter_dpp_populated)
+                            {
+                                auto bytes = sub->s->get_composite_option(RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP);
+                                if (bytes.size() != sizeof(rs2_temporal_filter_dpp_config))
+                                    throw std::runtime_error("HKR Temporal Filter DPP: unexpected payload size from get_composite_option");
+
+                                rs2_temporal_filter_dpp_config cfg{};
+                                memcpy(&cfg, bytes.data(), sizeof(cfg));
+                                sub->temporal_filter_dpp_enabled = cfg.enabled;
+                                sub->temporal_filter_dpp_smooth_alpha = cfg.smooth_alpha;
+                                sub->temporal_filter_dpp_smooth_delta = cfg.smooth_delta;
+                                sub->temporal_filter_dpp_persistency_index = cfg.persistency_index;
+                                sub->temporal_filter_dpp_populated = true;
+                            }
+
+                            bool enabled_bool = (sub->temporal_filter_dpp_enabled != 0);
+                            label = rsutils::string::from() << "Enabled##temporal_filter_dpp_enabled" << id;
+                            if (ImGui::Checkbox(label.c_str(), &enabled_bool))
+                                sub->temporal_filter_dpp_enabled = enabled_bool ? 1 : 0;
+
+                            label = rsutils::string::from() << "Smooth Alpha##temporal_filter_dpp_alpha" << id;
+                            ImGui::DragFloat(label.c_str(), &sub->temporal_filter_dpp_smooth_alpha, 0.01f, 0.f, 1.f);
+
+                            label = rsutils::string::from() << "Smooth Delta##temporal_filter_dpp_delta" << id;
+                            ImGui::DragInt(label.c_str(), &sub->temporal_filter_dpp_smooth_delta, 1, 1, 100);
+
+                            label = rsutils::string::from() << "Persistency Index##temporal_filter_dpp_persistency" << id;
+                            ImGui::DragInt(label.c_str(), &sub->temporal_filter_dpp_persistency_index, 1, 0, 8);
+
+                            label = rsutils::string::from() << "Send##temporal_filter_dpp_send" << id;
+                            if (ImGui::Button(label.c_str()))
+                            {
+                                rs2_temporal_filter_dpp_config 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;
+                                cfg.persistency_index = sub->temporal_filter_dpp_persistency_index;
+                                sub->s->set_composite_option(RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP, &cfg, sizeof(cfg));
+                            }
+                        }
+                        catch (const error& e)
+                        {
+                            error_message = error_to_string(e);
+                        }
+                        catch (const std::exception& e)
+                        {
+                            error_message = e.what();
+                        }
+
+                        ImGui::TreePop();
+                    }
+                }
+
                 draw_embedded_filters(sub, windows_width, window, viewer,
                     error_message, label, draw_later, update_read_only_options);
 

common/subdevice-model.h

@@ -230,6 +230,17 @@ namespace rs2
         std::vector<std::shared_ptr<embedded_filter_model>> embedded_filters;
         bool embedded_filters_enabled = true;
 
+        // PROTOTYPE / DEMO: UI state for the HKR Temporal Filter DPP "structured API" panel
+        // (gated on RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP appearing in
+        // sub->s->get_supported_composite_options() - see device-model.cpp). Widget values only
+        // change locally until "Apply" is pressed; that single click issues one
+        // set_composite_option() call, i.e. one atomic UVC transaction.
+        bool temporal_filter_dpp_populated = false;
+        int temporal_filter_dpp_enabled = 0;
+        float temporal_filter_dpp_smooth_alpha = 0.4f;
+        int temporal_filter_dpp_smooth_delta = 20;
+        int temporal_filter_dpp_persistency_index = 3;
+
         bool uvmapping_calib_full = false;
         device_model* dev_model;
         std::string _opt_base_label;

examples/CMakeLists.txt

@@ -58,5 +58,6 @@ add_subdirectory(on-chip-calib)
 add_subdirectory(eth-config)
 add_subdirectory(embedded-filters)
 add_subdirectory(object-detection)
+add_subdirectory(hkr-temporal-filter-dpp-mock)
 
 unset_security_flags_for_executable()

examples/hkr-temporal-filter-dpp-mock/CMakeLists.txt

@@ -0,0 +1,23 @@
+# License: Apache 2.0. See LICENSE file in root directory.
+# Copyright(c) 2026 RealSense, Inc. All Rights Reserved.
+cmake_minimum_required(VERSION 3.10)
+
+project(RealsenseExamplesHkrTemporalFilterDppMock)
+
+# PROTOTYPE / DEMO test scaffolding: proves the atomicity + round-trip behavior of the generic
+# "composite option" mechanism (include/librealsense2/h/rs_composite_option.h,
+# src/composite-option-interface.h) as applied to RS2_COMPOSITE_OPTION_HKR_TEMPORAL_FILTER_DPP,
+# against a fake in-memory librealsense::composite_option_interface implementation standing in for
+# real HKR/D555 hardware (librealsense::composite_xu_option, src/ds/composite-xu-option.h), which
+# is not present on this dev machine. Drives the mechanism through the REAL PUBLIC ENTRY POINTS
+# (rs2_set_composite_option/rs2_get_composite_option and the direct
+# rs2::options::get_composite_option()/set_composite_option() C++ methods - no casting/handle
+# type involved) rather than bypassing into an internal transport class directly, so it links
+# against realsense2 like any other example.
+add_executable(rs-hkr-temporal-filter-dpp-mock
+    rs-hkr-temporal-filter-dpp-mock.cpp
+)
+set_property(TARGET rs-hkr-temporal-filter-dpp-mock PROPERTY CXX_STANDARD 14)
+target_link_libraries(rs-hkr-temporal-filter-dpp-mock PRIVATE ${LRS_TARGET})
+set_target_properties (rs-hkr-temporal-filter-dpp-mock PROPERTIES FOLDER Examples)
+install(TARGETS rs-hkr-temporal-filter-dpp-mock RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})