Add rs2::option_ref()/option_handle/composite_option, mirroring rs2::frame's is<T>()/as<T>()

Make options first-class-castable in C++, the same way frames already are:

- rs2::options gains option_ref(rs2_option) - returns a lightweight, non-owning
  option_handle identifying a (this options object, id) pair. Named option_ref,
  not get_option_handle, to stay clearly distinct from the internal, differently-
  typed options_container::get_option_handler(). Available on both rs2::sensor
  and rs2::embedded_filter automatically, since both already inherit rs2::options.
- rs2::option_handle: is<T>()/as<T>() construct a T from *this and rely on its
  converting constructor to flag validity via operator bool(), never throwing -
  the exact same pattern as rs2::video_frame(const rs2::frame&).
- rs2::composite_option: the cast target. Its converting constructor calls the
  new rs2_is_option_extendable_to(RS2_EXTENSION_COMPOSITE_OPTION) check (guarded
  by a never-throwing rs2_supports_option() first, since - unlike the frame/sensor
  extension checks, which only ever risk a dynamic_cast - looking up an
  unregistered option id throws). get()/get_range() unwrap the SDK-allocated
  rs2_raw_data_buffer the same way rs2::safety_sensor::get_safety_preset does;
  set() takes a caller-owned buffer; is_read_only()/is_enabled()/get_description()
  delegate straight through (pure metadata, no value marshaling).

Author: Evgeni Raikhel

include/librealsense2/hpp/rs_composite_option.hpp

@@ -7,66 +7,174 @@
 #ifndef LIBREALSENSE_RS2_COMPOSITE_OPTION_HPP
 #define LIBREALSENSE_RS2_COMPOSITE_OPTION_HPP
 
-#include "rs_sensor.hpp"
+#include "rs_options.hpp"
 #include "../h/rs_composite_option.h"
 
+#include <memory>
+#include <vector>
+#include <cstdint>
+
 namespace rs2
 {
-    // Generic "composite option" extension: any sensor that supports AT LEAST ONE composite
-    // (multi-field, atomically-exchanged) option extends to this - see is<T>()/as<T>() in
-    // rs_types.hpp, backed by rs2_is_sensor_extendable_to(RS2_EXTENSION_COMPOSITE_OPTIONS).
-    // There is one wrapper class for every composite option, not one per feature: which option
-    // you are getting/setting is selected by the rs2_composite_option_id argument.
-    class composite_option_sensor : public sensor
+    // Lightweight, non-owning reference to a single (options-object, rs2_option id) pair -
+    // obtained via options::option_ref(). Mirrors rs2::frame's is<T>()/as<T>() dispatch
+    // (rs_frame.hpp / rs2_is_frame_extendable_to) exactly, just for options instead of frames:
+    // is<T>() / as<T>() construct a T from *this and rely on T's converting constructor to flag
+    // validity (see composite_option below), rather than throwing.
+    //
+    // Does NOT own the underlying rs2_options* - it shares the lifetime of whichever
+    // sensor/embedded_filter produced it via options::option_ref(); the caller must keep that
+    // object alive for as long as this handle (or anything cast from it) is used.
+    class option_handle
+    {
+    public:
+        option_handle() = default;
+
+        option_handle( std::shared_ptr< rs2_options > options, rs2_option id )
+            : _options( std::move( options ) )
+            , _id( id )
+        {
+        }
+
+        template< class T >
+        bool is() const
+        {
+            T extension( *this );
+            return extension;
+        }
+
+        template< class T >
+        T as() const
+        {
+            T extension( *this );
+            return extension;
+        }
+
+        rs2_option get_option_id() const { return _id; }
+
+        operator bool() const { return _valid && _options != nullptr; }
+
+    protected:
+        std::shared_ptr< rs2_options > _options;
+        rs2_option _id = RS2_OPTION_COUNT;
+        bool _valid = true;
+    };
+
+    // Generic "composite option" extension: any option that is a multi-field, atomically
+    // exchanged composite control (see rs_composite_option.h) extends to this - one wrapper
+    // class shared by every such option, not one per feature. Which option this refers to is
+    // carried by the underlying option_handle's id - obtain one via options::option_ref(id).
+    class composite_option : public option_handle
     {
     public:
-        composite_option_sensor(sensor s)
-            : sensor(s.get())
+        // Mirrors rs2::video_frame(const rs2::frame&) exactly (see rs_frame.hpp): checks the
+        // extension via the C API and marks itself invalid (never throws) on mismatch. Guarded
+        // by rs2_supports_option() first (a plain, never-throwing lookup) because - unlike
+        // rs2_is_sensor_extendable_to/rs2_is_frame_extendable_to, which only ever risk a
+        // dynamic_cast - rs2_is_option_extendable_to looks up the option by id first, which
+        // throws (surfaced as an rs2_error) if this id isn't registered on the container at all;
+        // that's a legitimate "not this option" case here, not an error to propagate.
+        composite_option( const option_handle & h )
+            : option_handle( h )
         {
-            rs2_error* e = nullptr;
-            if (rs2_is_sensor_extendable_to(_sensor.get(), RS2_EXTENSION_COMPOSITE_OPTIONS, &e) == 0 && !e)
+            rs2_error * e = nullptr;
+            bool extendable = _options && rs2_supports_option( _options.get(), _id, &e ) > 0;
+            error::handle( e );
+            if( extendable )
             {
-                _sensor.reset();
+                extendable = rs2_is_option_extendable_to( _options.get(), _id, RS2_EXTENSION_COMPOSITE_OPTION, &e ) > 0;
+                error::handle( e );
             }
-            error::handle(e);
+            if( ! extendable )
+                _valid = false;
         }
 
-        operator bool() const { return _sensor.get() != nullptr; }
-
-        // Single atomic UVC transaction (one set_xu round trip) - all fields of *data sent together.
-        void set_composite_option(rs2_composite_option_id option_id, const void* data, unsigned int data_size) const
+        // Single atomic UVC transaction (one set_xu round trip) - all fields of *data sent
+        // together. No ownership transfer - data remains caller-owned, like options::set_option.
+        void set( const void * data, size_t size ) const
         {
-            rs2_error* e = nullptr;
-            rs2_set_composite_option(_sensor.get(), option_id, data, data_size, &e);
-            error::handle(e);
+            rs2_error * e = nullptr;
+            rs2_set_composite_option( _options.get(), _id, data, static_cast< unsigned int >( size ), &e );
+            error::handle( e );
         }
 
         // 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. 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
+        // (the caller has no generic way to know this option's wire size in advance) and this
+        // wrapper hides the raw rs2_raw_data_buffer/manual-free entirely (mirrors
+        // rs2::safety_sensor::get_safety_preset's exact unwrap pattern), returning a plain
+        // std::vector<uint8_t> of the option's current raw payload bytes.
+        std::vector< uint8_t > get() const
+        {
+            rs2_error * e = nullptr;
+            auto buffer = rs2_get_composite_option( _options.get(), _id, &e );
+            return unwrap( buffer, e );
+        }
+
+        // Same unwrap pattern as get(), for the option's supported {min,max,step,def} - see
+        // rs_hkr_temporal_filter_dpp.h for RS2_OPTION_HKR_TEMPORAL_FILTER_DPP's range struct.
+        std::vector< uint8_t > get_range() const
+        {
+            rs2_error * e = nullptr;
+            auto buffer = rs2_get_composite_option_range( _options.get(), _id, &e );
+            return unwrap( buffer, e );
+        }
+
+        // Full functional parity with plain rs2::option-style metadata queries - pure
+        // metadata/no value-marshaling, so these just delegate through normally.
+        bool is_read_only() const
+        {
+            rs2_error * e = nullptr;
+            auto res = rs2_is_option_read_only( _options.get(), _id, &e );
+            error::handle( e );
+            return res > 0;
+        }
+
+        // Reflects real, current runtime availability (delegates to rs2_supports_option) - this
+        // is NOT the mechanism used to block scalar rs2_get_option/rs2_set_option access on a
+        // composite option (that's a hard-blocked, always-throws operation on the underlying
+        // option implementation - see librealsense::composite_xu_option).
+        bool is_enabled() const
         {
-            rs2_error* e = nullptr;
-            auto buffer = rs2_get_composite_option(_sensor.get(), option_id, &e);
+            rs2_error * e = nullptr;
+            auto res = rs2_supports_option( _options.get(), _id, &e );
+            error::handle( e );
+            return res > 0;
+        }
 
-            std::shared_ptr<const rs2_raw_data_buffer> list(buffer, rs2_delete_raw_data);
-            error::handle(e);
+        const char * get_description() const
+        {
+            rs2_error * e = nullptr;
+            auto res = rs2_get_option_description( _options.get(), _id, &e );
+            error::handle( e );
+            return res;
+        }
 
-            auto size = rs2_get_raw_data_size(list.get(), &e);
-            error::handle(e);
+    private:
+        static std::vector< uint8_t > unwrap( const rs2_raw_data_buffer * buffer, rs2_error * e )
+        {
+            std::shared_ptr< const rs2_raw_data_buffer > list( buffer, rs2_delete_raw_data );
+            error::handle( e );
 
-            auto start = rs2_get_raw_data(list.get(), &e);
-            error::handle(e);
+            rs2_error * e2 = nullptr;
+            auto size = rs2_get_raw_data_size( list.get(), &e2 );
+            error::handle( e2 );
 
-            std::vector<uint8_t> result;
-            result.insert(result.begin(), start, start + size);
+            auto start = rs2_get_raw_data( list.get(), &e2 );
+            error::handle( e2 );
 
+            std::vector< uint8_t > result;
+            result.insert( result.begin(), start, start + size );
             return result;
         }
     };
+
+    inline option_handle options::option_ref( rs2_option id ) const
+    {
+        // Non-owning: no-op deleter. The real object (sensor/embedded_filter) that _options
+        // aliases owns its own lifetime elsewhere - this handle just shares it, exactly as
+        // rs2::options itself only ever holds a raw, non-owning rs2_options* alias (see
+        // options::_options / options(rs2_options*) above).
+        return option_handle( std::shared_ptr< rs2_options >( _options, []( rs2_options * ) {} ), id );
+    }
 }
 #endif // LIBREALSENSE_RS2_COMPOSITE_OPTION_HPP

include/librealsense2/hpp/rs_options.hpp

@@ -12,6 +12,14 @@
 
 namespace rs2
 {
+    // Defined in rs_composite_option.hpp (included later by rs.hpp, after this header) - a
+    // lightweight, non-owning (options-object, rs2_option id) reference, obtained via
+    // options::option_ref() below and cast with is<T>()/as<T>() the same way rs2::frame is cast
+    // to rs2::video_frame etc. Forward-declared here so options::option_ref() can be declared
+    // (its out-of-line definition lives in rs_composite_option.hpp, once option_handle is fully
+    // defined).
+    class option_handle;
+
     class option_value
     {
         std::shared_ptr< const rs2_option_value > _value;
@@ -320,6 +328,18 @@ namespace rs2
             return options_list( sptr );
         };
 
+        /**
+        * Obtain a lightweight, non-owning handle identifying a single (this options object, id)
+        * pair - shares the lifetime of whichever sensor/embedded_filter this options object came
+        * from (does NOT take ownership of, or duplicate, the underlying handle). Cast it with
+        * is<T>()/as<T>() to a more specific type - e.g. is<composite_option>()/as<composite_option>()
+        * - the same way rs2::frame is cast to rs2::video_frame etc. See rs_composite_option.hpp.
+        * Named option_ref (not get_option_handle) to stay clearly distinct from the internal,
+        * same-ish-sounding options_container::get_option_handler().
+        * \param[in] id   option id to obtain a handle for
+        */
+        option_handle option_ref( rs2_option id ) const;
+
         options& operator=(const options& other)
         {
             _options = other._options;