Add typed composite-option cast helpers, document future MinZ versioning

rs_options.hpp: get_composite_option_as<T>()/get_composite_option_range_as<TRange>()/
set_composite_option_from<T>() wrap the existing raw-bytes methods with a size check
and, for structs carrying a `version` field (detected via SFINAE, no opt-in needed),
a check that it isn't the zero/"never populated" sentinel. Header-only, so this adds
no new exported symbols - the composite-option ABI waist is unchanged.

rs_hkr_minz_control.h: documents the fallback pattern for a future MinZ version that
outgrows the wire envelope's reserved params[5..7] room (peek the fixed-offset version
byte, dispatch into a tagged union) - illustrative only, no rs2_minz_control_v2 exists.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: Evgeni Raikhel

include/librealsense2/h/rs_hkr_minz_control.h

@@ -86,6 +86,56 @@ typedef struct rs2_minz_control_range
     rs2_minz_control def;
 } rs2_minz_control_range;
 
+/* ---------------------------------------------------------------------------------------------
+ * A NOTE ON FUTURE VERSIONING (documentation only - nothing below this point is compiled, and no
+ * rs2_minz_control_v2 exists today; this is a provision, not a feature).
+ * ---------------------------------------------------------------------------------------------
+ * rs2_minz_control::version exists so a future firmware revision can change this control's shape
+ * without breaking older hosts. The wire envelope already reserves params[5..7] for exactly that
+ * - the expected growth path is a new version populating a previously-reserved slot and bumping
+ * param_count. sizeof(rs2_minz_control) does not change in that case, and nothing below is
+ * needed: get_composite_option_as<rs2_minz_control>() keeps working unmodified, and it is
+ * param_count (not the C++ type) that tells the caller how many fields are meaningful.
+ *
+ * If a future version ever outgrows the envelope's reserved room - a genuine breaking wire
+ * change - sizeof() DOES change, and no C++ trick lets `auto` deduce "whichever struct matches
+ * whatever version comes back at runtime": `auto` only ever deduces the one type a function is
+ * declared to return. The pattern to reach for at that point is: peek the version field (always
+ * fixed at byte 0 - this struct's one permanent invariant) BEFORE committing to a struct type,
+ * then dispatch into a small tagged union that IS the one fixed type the caller's `auto` binds
+ * to:
+ *
+ *     typedef struct rs2_minz_control_v2 { ... } rs2_minz_control_v2;   // whatever v2 becomes
+ *
+ *     struct rs2_minz_control_any
+ *     {
+ *         uint8_t version;                // which member of `as` is populated
+ *         union { rs2_minz_control v1; rs2_minz_control_v2 v2; } as;
+ *     };
+ *
+ *     rs2_minz_control_any get_minz_control_versioned( const rs2::options & sensor, rs2_composite_option_id id )
+ *     {
+ *         std::vector<uint8_t> raw = sensor.get_composite_option( id );   // no cast yet
+ *         rs2_minz_control_any result{};
+ *         result.version = raw[0];                                       // fixed offset, by contract
+ *         switch( result.version )
+ *         {
+ *         case 1:  memcpy( &result.as.v1, raw.data(), sizeof( rs2_minz_control ) );    break;
+ *         case 2:  memcpy( &result.as.v2, raw.data(), sizeof( rs2_minz_control_v2 ) ); break;
+ *         default: throw std::runtime_error( "unrecognized MinZ control wire version" );
+ *         }
+ *         return result;
+ *     }
+ *
+ *     auto cfg = get_minz_control_versioned( sensor, id );   // auto -> rs2_minz_control_any, fixed
+ *     if( cfg.version == 1 ) { use cfg.as.v1 ... }
+ *
+ * This tagged-union shape works unmodified in C99 too - no templates involved, just a struct
+ * with a tag and a union. It is a SEPARATE versioning axis from rs2_minz_control_range::version
+ * above, which versions the {min,max,step,def} WRAPPER shape, not this struct's own payload
+ * shape - the two can change independently.
+ * --------------------------------------------------------------------------------------------- */
+
 #ifdef __cplusplus
 }
 #endif

include/librealsense2/hpp/rs_options.hpp

@@ -12,6 +12,11 @@
 #include <vector>
 #include <cstdint>
 #include <cstddef>
+#include <cstring>
+#include <string>
+#include <stdexcept>
+#include <type_traits>
+#include <utility>
 
 
 namespace rs2
@@ -372,6 +377,53 @@ namespace rs2
             return unwrap_raw_data_buffer( buffer, e );
         }
 
+        /**
+        * typed counterpart to get_composite_option() - casts the raw payload directly into T
+        * instead of handing back bytes for the caller to memcpy themselves. Validates that the
+        * device returned exactly sizeof(T) bytes, and - only for structs that carry a `version`
+        * field, e.g. rs2_minz_control - that it isn't the "never populated" sentinel (0).
+        * \param[in] id   composite option id to read
+        * \return         T, populated from the option's current raw payload
+        */
+        template< typename T >
+        T get_composite_option_as( rs2_composite_option_id id ) const
+        {
+            T value{};
+            cast_composite_payload( get_composite_option( id ), value );
+            return value;
+        }
+
+        /**
+        * typed counterpart to get_composite_option_range() - casts the raw {min,max,step,def}
+        * payload directly into TRange (e.g. rs2_minz_control_range) instead of handing back
+        * bytes. Same size/version validation as get_composite_option_as().
+        * \param[in] id   composite option id to read
+        * \return         TRange, populated from the option's raw range payload
+        */
+        template< typename TRange >
+        TRange get_composite_option_range_as( rs2_composite_option_id id ) const
+        {
+            TRange range{};
+            cast_composite_payload( get_composite_option_range( id ), range );
+            return range;
+        }
+
+        /**
+        * typed counterpart to set_composite_option() - sends value itself instead of a raw
+        * pointer+size pair. For structs that carry a `version` field, rejects a value that is
+        * still 0 (default-initialized) instead of silently sending an unpopulated wire header -
+        * the most likely real bug being caught here is a get-modify-set that only touched one
+        * field and left the rest, header included, zero-initialized.
+        * \param[in] id      composite option id to write
+        * \param[in] value   the caller's struct matching the option's documented wire layout
+        */
+        template< typename T >
+        void set_composite_option_from( rs2_composite_option_id id, const T & value ) const
+        {
+            check_version_populated( value );
+            set_composite_option( id, &value, sizeof( T ) );
+        }
+
         /**
         * check if particular composite option is supported (and currently enabled)
         * \param[in] id   composite option id to be checked
@@ -476,6 +528,56 @@ namespace rs2
             return result;
         }
 
+        // ---- typed composite-option cast helpers (get_composite_option_as() and friends) -----
+        //
+        // Detects whether T has a `.version` member WITHOUT requiring T to opt in explicitly -
+        // this alone covers every composite-option struct in the SDK today: both range wrappers
+        // (rs2_temporal_filter_dpp_range::version, rs2_minz_control_range::version) and any value
+        // struct that embeds its own wire header (rs2_minz_control::version). A struct with no
+        // such field (rs2_temporal_filter_dpp_config) falls through to the no-op overload below -
+        // there is nothing to check for it.
+        template< typename U >
+        class has_version_member
+        {
+            template< typename V > static auto test( int ) -> decltype( std::declval< V >().version, std::true_type{} );
+            template< typename > static std::false_type test( ... );
+        public:
+            static const bool value = decltype( test< U >( 0 ) )::value;
+        };
+
+        template< typename T >
+        static typename std::enable_if< ! has_version_member< T >::value >::type
+        check_version_populated( const T & )
+        {
+            // T has no version field (e.g. rs2_temporal_filter_dpp_config) - nothing to check.
+        }
+
+        template< typename T >
+        static typename std::enable_if< has_version_member< T >::value >::type
+        check_version_populated( const T & value )
+        {
+            // Convention across every struct that carries this field (see rs_composite_option.h
+            // and the per-feature headers it points to): valid versions start at 1. A 0 means
+            // "never populated" - either get_composite_option_as() got back fewer meaningful
+            // bytes than expected, or set_composite_option_from() is about to send a
+            // default-initialized header the device never asked for.
+            if( value.version == 0 )
+                throw std::runtime_error( "composite option struct has an unpopulated version field (0) "
+                                           "- wrong struct for this option id, or a zero-initialized "
+                                           "header about to be sent?" );
+        }
+
+        template< typename T >
+        static void cast_composite_payload( const std::vector< uint8_t > & raw, T & out )
+        {
+            if( raw.size() != sizeof( T ) )
+                throw std::runtime_error( "composite option payload size (" + std::to_string( raw.size() )
+                                           + ") does not match sizeof(T) (" + std::to_string( sizeof( T ) )
+                                           + ") - wrong struct for this option id?" );
+            std::memcpy( &out, raw.data(), sizeof( T ) );
+            check_version_populated( out );
+        }
+
         rs2_options* _options;
     };