Exposes RealSense processing-block functionality for C compilers. More...

#include "rs_types.h"
#include "rs_sensor.h"
#include "rs_config.h"

Functions
rs2_pipeline *	rs2_create_pipeline (rs2_context ctx, rs2_error *error)

void	rs2_pipeline_stop (rs2_pipeline pipe, rs2_error *error)

rs2_frame *	rs2_pipeline_wait_for_frames (rs2_pipeline pipe, unsigned int timeout_ms, rs2_error *error)

int	rs2_pipeline_poll_for_frames (rs2_pipeline pipe, rs2_frame output_frame, rs2_error *error)

int	rs2_pipeline_try_wait_for_frames (rs2_pipeline pipe, rs2_frame output_frame, unsigned int timeout_ms, rs2_error *error)

void	rs2_delete_pipeline (rs2_pipeline *pipe)

rs2_pipeline_profile *	rs2_pipeline_start (rs2_pipeline pipe, rs2_error *error)

rs2_pipeline_profile *	rs2_pipeline_start_with_config (rs2_pipeline pipe, rs2_config config, rs2_error **error)

rs2_pipeline_profile *	rs2_pipeline_start_with_callback (rs2_pipeline pipe, rs2_frame_callback_ptr on_frame, void user, rs2_error **error)

rs2_pipeline_profile *	rs2_pipeline_start_with_callback_cpp (rs2_pipeline pipe, rs2_frame_callback callback, rs2_error **error)

rs2_pipeline_profile *	rs2_pipeline_start_with_config_and_callback (rs2_pipeline pipe, rs2_config config, rs2_frame_callback_ptr on_frame, void user, rs2_error *error)

rs2_pipeline_profile *	rs2_pipeline_start_with_config_and_callback_cpp (rs2_pipeline pipe, rs2_config config, rs2_frame_callback callback, rs2_error *error)

rs2_pipeline_profile *	rs2_pipeline_get_active_profile (rs2_pipeline pipe, rs2_error *error)

rs2_device *	rs2_pipeline_profile_get_device (rs2_pipeline_profile profile, rs2_error *error)

rs2_stream_profile_list *	rs2_pipeline_profile_get_streams (rs2_pipeline_profile profile, rs2_error *error)

void	rs2_delete_pipeline_profile (rs2_pipeline_profile *profile)

Detailed Description

Exposes RealSense processing-block functionality for C compilers.

Function Documentation

◆ rs2_create_pipeline()

rs2_pipeline* rs2_create_pipeline	(	rs2_context *	ctx,
		rs2_error **	error
	)

Create a pipeline instance The pipeline simplifies the user interaction with the device and computer vision processing modules. The class abstracts the camera configuration and streaming, and the vision modules triggering and threading. It lets the application focus on the computer vision output of the modules, or the device output data. The pipeline can manage computer vision modules, which are implemented as a processing blocks. The pipeline is the consumer of the processing block interface, while the application consumes the computer vision interface.

Parameters

[in]	ctx	context
[out]	error	if non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_delete_pipeline()

void rs2_delete_pipeline ( rs2_pipeline * pipe )

Delete a pipeline instance. Upon destruction, the pipeline will implicitly stop itself

Parameters

[in] pipe to delete

◆ rs2_delete_pipeline_profile()

void rs2_delete_pipeline_profile ( rs2_pipeline_profile * profile )

Deletes an instance of a pipeline profile

Parameters

[in] profile A pointer to an instance of a pipeline profile

◆ rs2_pipeline_get_active_profile()

rs2_pipeline_profile* rs2_pipeline_get_active_profile	(	rs2_pipeline *	pipe,
		rs2_error **	error
	)

Return the active device and streams profiles, used by the pipeline. The pipeline streams profiles are selected during start(). The method returns a valid result only when the pipeline is active - between calls to start() and stop(). After stop() is called, the pipeline doesn't own the device, thus, the pipeline selected device may change in subsequent activations.

Parameters

[in]	pipe	a pointer to an instance of the pipeline
[out]	error	if non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns: The actual pipeline device and streams profile, which was successfully configured to the streaming device on start.

◆ rs2_pipeline_poll_for_frames()

int rs2_pipeline_poll_for_frames	(	rs2_pipeline *	pipe,
		rs2_frame **	output_frame,
		rs2_error **	error
	)

Check if a new set of frames is available and retrieve the latest undelivered set. The frames set includes time-synchronized frames of each enabled stream in the pipeline. The method returns without blocking the calling thread, with status of new frames available or not. If available, it fetches the latest frames set. Device frames, which were produced while the function wasn't called, are dropped. To avoid frame drops, this method should be called as fast as the device frame rate. The application can maintain the frames handles to defer processing. However, if the application maintains too long history, the device may lack memory resources to produce new frames, and the following calls to this method shall return no new frames, until resources are retained.

Parameters

[in]	pipe	the pipeline
[out]	output_frame	frame handle to be released using rs2_release_frame
[out]	error	if non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns: true if new frame was stored to output_frame

◆ rs2_pipeline_profile_get_device()

rs2_device* rs2_pipeline_profile_get_device	(	rs2_pipeline_profile *	profile,
		rs2_error **	error
	)

Retrieve the device used by the pipeline. The device class provides the application access to control camera additional settings - get device information, sensor options information, options value query and set, sensor specific extensions. Since the pipeline controls the device streams configuration, activation state and frames reading, calling the device API functions, which execute those operations, results in unexpected behavior. The pipeline streaming device is selected during pipeline start(). Devices of profiles, which are not returned by pipeline start() or get_active_profile(), are not guaranteed to be used by the pipeline.

Parameters

[in]	profile	A pointer to an instance of a pipeline profile
[out]	error	if non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns: rs2_device* The pipeline selected device

◆ rs2_pipeline_profile_get_streams()

rs2_stream_profile_list* rs2_pipeline_profile_get_streams	(	rs2_pipeline_profile *	profile,
		rs2_error **	error
	)

Return the selected streams profiles, which are enabled in this profile.

Parameters

[in]	profile	A pointer to an instance of a pipeline profile
[out]	error	if non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns: list of stream profiles

◆ rs2_pipeline_start()

rs2_pipeline_profile* rs2_pipeline_start	(	rs2_pipeline *	pipe,
		rs2_error **	error
	)

Start the pipeline streaming with its default configuration. The pipeline streaming loop captures samples from the device, and delivers them to the attached computer vision modules and processing blocks, according to each module requirements and threading model. During the loop execution, the application can access the camera streams by calling wait_for_frames() or poll_for_frames(). The streaming loop runs until the pipeline is stopped. Starting the pipeline is possible only when it is not started. If the pipeline was started, an exception is raised.

Parameters

[in]	pipe	a pointer to an instance of the pipeline
[out]	error	if non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns: The actual pipeline device and streams profile, which was successfully configured to the streaming device.

◆ rs2_pipeline_start_with_callback()

rs2_pipeline_profile* rs2_pipeline_start_with_callback	(	rs2_pipeline *	pipe,
		rs2_frame_callback_ptr	on_frame,
		void *	user,
		rs2_error **	error
	)

Start the pipeline streaming with its default configuration. The pipeline captures samples from the device, and delivers them to the through the provided frame callback. Starting the pipeline is possible only when it is not started. If the pipeline was started, an exception is raised. When starting the pipeline with a callback both wait_for_frames() or poll_for_frames() will throw exception.

Parameters

[in]	pipe	A pointer to an instance of the pipeline
[in]	on_frame	function pointer to register as per-frame callback
[in]	user	auxiliary data the user wishes to receive together with every frame callback
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns: The actual pipeline device and streams profile, which was successfully configured to the streaming device.

◆ rs2_pipeline_start_with_callback_cpp()

rs2_pipeline_profile* rs2_pipeline_start_with_callback_cpp	(	rs2_pipeline *	pipe,
		rs2_frame_callback *	callback,
		rs2_error **	error
	)

Start the pipeline streaming with its default configuration. The pipeline captures samples from the device, and delivers them to the through the provided frame callback. Starting the pipeline is possible only when it is not started. If the pipeline was started, an exception is raised. When starting the pipeline with a callback both wait_for_frames() or poll_for_frames() will throw exception.

Parameters

[in]	pipe	A pointer to an instance of the pipeline
[in]	callback	callback object created from c++ application. ownership over the callback object is moved into the relevant streaming lock
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns: The actual pipeline device and streams profile, which was successfully configured to the streaming device.

◆ rs2_pipeline_start_with_config()

rs2_pipeline_profile* rs2_pipeline_start_with_config	(	rs2_pipeline *	pipe,
		rs2_config *	config,
		rs2_error **	error
	)

Start the pipeline streaming according to the configuraion. The pipeline streaming loop captures samples from the device, and delivers them to the attached computer vision modules and processing blocks, according to each module requirements and threading model. During the loop execution, the application can access the camera streams by calling wait_for_frames() or poll_for_frames(). The streaming loop runs until the pipeline is stopped. Starting the pipeline is possible only when it is not started. If the pipeline was started, an exception is raised. The pipeline selects and activates the device upon start, according to configuration or a default configuration. When the rs2::config is provided to the method, the pipeline tries to activate the config resolve() result. If the application requests are conflicting with pipeline computer vision modules or no matching device is available on the platform, the method fails. Available configurations and devices may change between config resolve() call and pipeline start, in case devices are connected or disconnected, or another application acquires ownership of a device.

Parameters

[in]	pipe	a pointer to an instance of the pipeline
[in]	config	A rs2::config with requested filters on the pipeline configuration. By default no filters are applied.
[out]	error	if non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns: The actual pipeline device and streams profile, which was successfully configured to the streaming device.

◆ rs2_pipeline_start_with_config_and_callback()

rs2_pipeline_profile* rs2_pipeline_start_with_config_and_callback	(	rs2_pipeline *	pipe,
		rs2_config *	config,
		rs2_frame_callback_ptr	on_frame,
		void *	user,
		rs2_error **	error
	)

Start the pipeline streaming according to the configuraion. The pipeline captures samples from the device, and delivers them to the through the provided frame callback. Starting the pipeline is possible only when it is not started. If the pipeline was started, an exception is raised. When starting the pipeline with a callback both wait_for_frames() or poll_for_frames() will throw exception. The pipeline selects and activates the device upon start, according to configuration or a default configuration. When the rs2::config is provided to the method, the pipeline tries to activate the config resolve() result. If the application requests are conflicting with pipeline computer vision modules or no matching device is available on the platform, the method fails. Available configurations and devices may change between config resolve() call and pipeline start, in case devices are connected or disconnected, or another application acquires ownership of a device.

Parameters

[in]	pipe	A pointer to an instance of the pipeline
[in]	config	A rs2::config with requested filters on the pipeline configuration. By default no filters are applied.
[in]	on_frame	function pointer to register as per-frame callback
[in]	user	auxiliary data the user wishes to receive together with every frame callback
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns: The actual pipeline device and streams profile, which was successfully configured to the streaming device.

◆ rs2_pipeline_start_with_config_and_callback_cpp()

rs2_pipeline_profile* rs2_pipeline_start_with_config_and_callback_cpp	(	rs2_pipeline *	pipe,
		rs2_config *	config,
		rs2_frame_callback *	callback,
		rs2_error **	error
	)

Start the pipeline streaming according to the configuraion. The pipeline captures samples from the device, and delivers them to the through the provided frame callback. Starting the pipeline is possible only when it is not started. If the pipeline was started, an exception is raised. When starting the pipeline with a callback both wait_for_frames() or poll_for_frames() will throw exception. The pipeline selects and activates the device upon start, according to configuration or a default configuration. When the rs2::config is provided to the method, the pipeline tries to activate the config resolve() result. If the application requests are conflicting with pipeline computer vision modules or no matching device is available on the platform, the method fails. Available configurations and devices may change between config resolve() call and pipeline start, in case devices are connected or disconnected, or another application acquires ownership of a device.

Parameters

[in]	pipe	A pointer to an instance of the pipeline
[in]	config	A rs2::config with requested filters on the pipeline configuration. By default no filters are applied.
[in]	callback	callback object created from c++ application. ownership over the callback object is moved into the relevant streaming lock
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns: The actual pipeline device and streams profile, which was successfully configured to the streaming device.

◆ rs2_pipeline_stop()

void rs2_pipeline_stop	(	rs2_pipeline *	pipe,
		rs2_error **	error
	)

Stop the pipeline streaming. The pipeline stops delivering samples to the attached computer vision modules and processing blocks, stops the device streaming and releases the device resources used by the pipeline. It is the application's responsibility to release any frame reference it owns. The method takes effect only after start() was called, otherwise an exception is raised.

Parameters

[in]	pipe	pipeline
[out]	error	if non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_pipeline_try_wait_for_frames()

int rs2_pipeline_try_wait_for_frames	(	rs2_pipeline *	pipe,
		rs2_frame **	output_frame,
		unsigned int	timeout_ms,
		rs2_error **	error
	)

Wait until a new set of frames becomes available. The frames set includes time-synchronized frames of each enabled stream in the pipeline. The method blocks the calling thread, and fetches the latest unread frames set. Device frames, which were produced while the function wasn't called, are dropped. To avoid frame drops, this method should be called as fast as the device frame rate. The application can maintain the frames handles to defer processing. However, if the application maintains too long history, the device may lack memory resources to produce new frames, and the following call to this method shall fail to retrieve new frames, until resources are retained.

Parameters

[in]	pipe	the pipeline
[in]	timeout_ms	max time in milliseconds to wait until a frame becomes available
[out]	output_frame	frame handle to be released using rs2_release_frame
[out]	error	if non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns: true if new frame was stored to output_frame

◆ rs2_pipeline_wait_for_frames()

rs2_frame* rs2_pipeline_wait_for_frames	(	rs2_pipeline *	pipe,
		unsigned int	timeout_ms,
		rs2_error **	error
	)

Wait until a new set of frames becomes available. The frames set includes time-synchronized frames of each enabled stream in the pipeline. The method blocks the calling thread, and fetches the latest unread frames set. Device frames, which were produced while the function wasn't called, are dropped. To avoid frame drops, this method should be called as fast as the device frame rate. The application can maintain the frames handles to defer processing. However, if the application maintains too long history, the device may lack memory resources to produce new frames, and the following call to this method shall fail to retrieve new frames, until resources are retained.

Parameters

[in]	pipe	the pipeline
[in]	timeout_ms	Max time in milliseconds to wait until an exception will be thrown
[out]	error	if non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns: Set of coherent frames

Functions

Detailed Description

Function Documentation

◆ rs2_create_pipeline()

◆ rs2_delete_pipeline()

◆ rs2_delete_pipeline_profile()

◆ rs2_pipeline_get_active_profile()

◆ rs2_pipeline_poll_for_frames()

◆ rs2_pipeline_profile_get_device()

◆ rs2_pipeline_profile_get_streams()

◆ rs2_pipeline_start()

◆ rs2_pipeline_start_with_callback()

◆ rs2_pipeline_start_with_callback_cpp()

◆ rs2_pipeline_start_with_config()

◆ rs2_pipeline_start_with_config_and_callback()

◆ rs2_pipeline_start_with_config_and_callback_cpp()

◆ rs2_pipeline_stop()

◆ rs2_pipeline_try_wait_for_frames()

◆ rs2_pipeline_wait_for_frames()