Class VideoAcquisitionOperator

• Defined in File video_acquisition_operator.hpp

Base Type

• public holoscan::Operator (Class Operator)

class VideoAcquisitionOperator : public holoscan::Operator

Base class for video acquisition (capture) operators.

Declares a standard signal output carrying holoscan::gxf::Entity (VideoBuffer or Tensor payload), matching V4L2VideoCaptureOp and composable with format conversion and Holoviz.

Subclasses must implement compute(). They may override query_capabilities() to query vendor SDKs without starting capture; the default implementation derives a minimal snapshot from configured parameters.

==Dynamic Port Allocation==

The number of output streams is set via the num_streams constructor parameter (default 1). Because make_operator calls the constructor before setup(), the stream count is available at port-registration time — only the requested number of ports are created. All registered ports get proper backpressure scheduling (no dormant ports with ConditionType::kNone).

==num_streams vs channel_indices==

num_streams controls port allocation (how many output ports setup() registers). channel_indices is a capability-reporting parameter that describes which hardware channels appear in the VideoCaptureCapabilities snapshot. These are intentionally independent: a singleton operator wrapping a vendor SDK that manages its own multiplexing may have num_streams=1 but channel_indices={0,1,2,3} to expose all channels the SDK reports. Conversely, num_streams=4 with empty channel_indices reports a single default channel in the capabilities.

==Named Outputs==

• signal : stream 0 (std::shared_ptr<holoscan::gxf::Entity>), always registered.

• signal_1 … signal_N : additional streams, registered only when num_streams > 1. Subclasses call emit_capture_stream() with index 0 … num_streams() - 1.

==Parameters==

• backend_id: Logical backend name for capability reporting (e.g. “v4l2”, “vendor.aja”).

• channel_index: Zero-based channel index when one channel per operator instance.

• channel_indices: Optional list of channel indices for multi-channel singleton-SDK fallback When non-empty, operators may treat this as the authoritative channel set.

• uri: Device path, device index string, or stream URI.

• width, height: Requested frame size; 0 means device default / unspecified.

• frame_rate: Requested frame rate; 0.f means unspecified.

• pixel_format: Requested pixel format token (fourcc or vendor-specific label).

• color_space: Requested color space (auto, bt709, …).

• transport: Hint for VideoTransport (auto, sdi, hdmi, ethernet, v4l2, …).

• vendor_extensions: Map of vendor-specific keys (vendor.<name>.<param>) as a YAML map

Public Functions

HOLOSCAN_OPERATOR_FORWARD_ARGS (VideoAcquisitionOperator) VideoAcquisitionOperator()=default

explicit VideoAcquisitionOperator(uint32_t num_streams)

Construct with a specific number of output streams.

Parameters

num_streams – Number of output ports to register (1 .. kVideoIoMaxStreams). Clamped to [1, kVideoIoMaxStreams]. Passed as a constructor argument so that setup() can read it before port registration (make_operator lifecycle).

HOLOSCAN_OPERATOR_FORWARD_TEMPLATE () explicit VideoAcquisitionOperator(uint32_t num_streams

Construct with a specific stream count and forwarded Arg / ArgList arguments.

Enables make_operator<Derived>("name", num_streams, Arg("key", val), ...).

inline ArgT ArgsT std::min (num_streams, video_io::kVideoIoMaxStreams)))

virtual void setup(OperatorSpec &spec) override

Define the operator specification.

Parameters

spec – The reference to the operator specification.

virtual void initialize() override

Initialize the operator.

This function is called when the fragment is initialized by Executor::initialize_fragment().

virtual video_io::VideoCaptureCapabilities query_capture_capabilities() const

video_io::VideoDeviceCapabilities query_capabilities() const

inline uint64_t dropped_frame_count() const

inline uint64_t acquired_frame_count() const

bool is_capture_stream_enabled(uint32_t stream_index) const

Returns

true if stream_index < num_streams().

inline uint32_t num_streams() const

Returns

Number of output streams registered in setup().

Public Members

ArgT &&arg

ArgT ArgsT && args

Protected Functions

inline void note_dropped_frame()

inline void note_acquired_frame()

void emit_capture_stream(OutputContext &op_output, uint32_t stream_index, holoscan::gxf::Entity &entity)

Emit an entity on the given capture stream port.

The entity remains valid after this call (the underlying GXF handle is shared, not moved). Throws std::out_of_range if stream_index >= num_streams().

virtual video_io::VideoCaptureCapabilities build_capture_capabilities_from_parameters() const

virtual void compute(InputContext &op_input, OutputContext &op_output, ExecutionContext &context) override = 0

Implement the compute method.

This method is called by the runtime multiple times. The runtime calls this method until the operator is stopped.

Parameters

• op_input – The input context of the operator.

• op_output – The output context of the operator.

• context – The execution context of the operator.

Protected Attributes

Parameter<std::string> backend_id_

Parameter<uint32_t> channel_index_

Parameter<std::vector<uint32_t>> channel_indices_

Parameter<std::string> uri_

Parameter<uint32_t> width_

Parameter<uint32_t> height_

Parameter<float> frame_rate_

Parameter<std::string> pixel_format_

Parameter<std::string> color_space_

Parameter<std::string> transport_

Parameter<YAML::Node> vendor_extensions_

Protected Static Functions

static std::string capture_output_port_name(uint32_t stream_index)

Return the output port name for a given stream index.

Index 0 returns "signal" (not "signal_0") for backward compatibility with single-stream operators such as V4L2VideoCaptureOp. Indices 1+ return "signal_1", "signal_2", etc. Validates against kVideoIoMaxStreams (global max), not the per-instance num_streams().