Pipeline changes

[zivsha]

Comprehensive API refactoring of pipeline.

Split pipeline functionality into 3 classes: config, profile, pipeline.
Updated all samples, tools and tests to new API.

Previous API had a single class that encapsulated all capabilities, of both configuring, selecting and streaming with rs2::pipeline. These capabilities have been split apart now for the simplest use, without any configuration requirements, the pipeline remains similar to before.

rs2::config - responsible for configuration constraints
rs2::pipeline_profile - stateless object representing the device and streams of the pipeline (or of the resolved configuration)
rs2::pipeline - facade for streaming over RealSense devices and in the future also managing computer vision modules.

Pipeline API usage

Pipeline Creation

rs2::pipeline pipe;

Starting streaming with default configuration:

rs2::pipeline pipe;
pipe.start();

The start function now returns a rs2::pipeline_profile which represents the profile that the pipeline chose to start the device with:

rs2::pipeline pipe;
rs2::pipeline_profile profile = pipe.start();

Getting the device and active streams

Using the rs2::pipeline_profile we can get the rs2::device and rs2::stream_profiles:

rs2::pipeline pipe;
rs2::pipeline_profile profile = pipe.start();

rs2::device dev = profile.get_device();
std::vector<stream_profile> streams =  profile.get_streams()

The rs2::pipeline_profile can also be retrieved from an already started pipeline by calling the get_active_profile function:

//pipe.start();

rs2::pipeline_profile profile = pipe.get_active_profile();

Getting Frames

In order to get frames from an active rs2::pipeline we have 2 methods:

Blocking

rs2::pipeline pipe;
pipe.start();

rs2::frameset frames = pipe.wait_for_frames(); //Blocking call

Non Blocking

rs2::pipeline pipe;
pipe.start();

rs2::frameset frames;
if(pipe.poll_for_frames(frames)) //Non blocking call
{
    //Use frames
}

Configuring the pipeline

The new API provides the rs2::config class that enables pipeline users to add constraints on which device and/or which streams that pipeline will use.

Creating a default configuration

rs2::config cfg;

This will create a default configuration object that has no constraints.

The pipeline has an overload for the start function that takes a rs2::config:

rs2::config cfg;
rs2::pipeline pipe;
pipe.start(cfg);

Passing this default configuration to the pipeline::start method is equivalent to calling the pipeline::start without any parameters.

Adding constraints to the configuraion

The rs2::config class has a number of functions that allow users to add constrains on the pipeline

Selecting a certain stream

To enable a specific stream, simply call the rs2::config::enable_stream function with the desired stream:

rs2::config cfg;
cfg.enable_stream(RS2_STREAM_DEPTH);
rs2::pipeline pipe;
pipe.start(cfg);

The above will indicate that the user is requesting the pipeline to start with a device that provides a depth stream.

If a certain device has a sensor that provides more than one stream of the same type, it is possible by passing a stream type and a corresponding stream index:

rs2::config cfg;
cfg.enable_stream(RS2_STREAM_INFRARED, 1);
rs2::pipeline pipe;
pipe.start(cfg);

This will indicate that the user wants IR #1 to be streaming, and not just any IR stream.

Selecting a certain resolution / FPS / Format

The rs2::config::enable_stream has several overloads which allows users to easily specify a certain resolution, frame rate and/or format. In any case, the stream type is required to be specified.

rs2::config cfg;
cfg.enable_stream(RS2_STREAM_COLOR, 1920, 1080);
rs2::pipeline pipe;
pipe.start(cfg);

This will indicate that the user wants a color stream with a FHD resolution.

Selecting a specific device

The rs2::config allows users to indicate which specific device they want to use.

Selecting device by serial number

If you know the serial number of the device you wish to use, you can specify it to enable_device:

const std::string my_D400_camera_serial = "123456789";

rs2::config cfg;
cfg.enable_device(my_D400_camera_serial );
rs2::pipeline pipe;
pipe.start(cfg);

Selecting a device from file (playback)

rs2::config cfg;
cfg.enable_device_from_file("my_recorded_file.bag");
rs2::pipeline pipe;
pipe.start(cfg);

Enabling recording to file

The configuration object can be used to indicate that the device which will be selected should be recorded to file. To allow this, simply call:

rs2::config cfg;
cfg.enable_record_to_file("record_sequence1.bag");
rs2::pipeline pipe;
pipe.start(cfg); //Frames and changes to sensors will be saved to file

Testing a configuration

In order to allow users with means of testing whether the constraints on a configuration are valid the rs2::config provides two methods of resolution:

• bool rs2::config::can_resolve(...) - returns true if and only if a valid resolution can be made.
• rs2::pipeline_profile rs2::config::resolve(...) - Throws an exception on failure, returns the profile that will be chosen by the pipeline in case of successful resolution.

The first function simply indicates if the configuration is valid. This use case will be common if your application programmatically tries to create a valid rs2::config:

rs2::config cfg;
cfg.enable_stream(RS2_STREAM_COLOR, 123, 456); //INVALID RESOLUTION

rs2::pipeline pipe;
if(cfg.can_resolve(pipe))
{
    pipe.start(cfg);
}
else
{
    pipe.start();
}

The second option is request the rs2::config to try to resolve and return the rs2::pipeline_profile that will be used if that configuration were to be passed to pipeline::start:

rs2::config cfg;
cfg.enable_stream(RS2_STREAM_COLOR, 640, 480); //Valid resolution (for most cameras)

rs2::pipeline pipe;
try
{
    rs2::pipeline_profile profile = cfg.resolve(pipe);
    rs2::device dev = profile.get_device();
    //Use the device pre-streaming
}
catch(const std::exception& e)
{
    //recover, exit, or any other choice
}

[dorodnic]

Please bump version to 2.8.0
and merge with dev branch

[dorodnic]

Please use spaces