Configuration of effects and frame processor. More...

#include <vb_sdk/pipeline.h>

Inheritance diagram for tsvb::IPipeline:

Public Member Functions
virtual PipelineError	setConfiguration (const IPipelineConfiguration *config)=0
	Configures the pipeline, for example whether to use GPU or CPU for processing.
virtual IPipelineConfiguration *	copyConfiguration () const =0
	Returns a copy of the current configuration. The caller is responsible for releasing it.
virtual IPipelineConfiguration *	copyDefaultConfiguration () const =0
	Returns a copy of the default configuration. The caller is responsible for releasing it.
virtual PipelineError	enableBlurBackground (float blurPower)=0
	Enables background blur.
virtual void	disableBackgroundBlur ()=0
	Disables background blur.
virtual bool	getBlurBackgroundState (float *blurPower) const =0
	Returns true if background blur is enabled, otherwise false.
virtual PipelineError	enableReplaceBackground (IReplacementController **controller)=0
	Enables background replacement.
virtual void	disableReplaceBackground ()=0
	Disables background replacement.
virtual bool	getReplaceBackgroundState () const =0
	Returns true if background replacement is enabled, otherwise false.
virtual PipelineError	enableBeautification ()=0
	Enables face beautification.
virtual void	disableBeautification ()=0
	Disables face beautification.
virtual void	setBeautificationLevel (float level)=0
	Sets the face beautification level.
virtual float	getBeautificationLevel () const =0
	Returns the current beautification level.
virtual PipelineError	enableSmartZoom ()=0
	Enables smart zoom. Smart zoom crops around the face.
virtual void	disableSmartZoom ()=0
	Disables smart zoom.
virtual void	setSmartZoomLevel (float level)=0
	Sets the smart zoom level.
virtual float	getSmartZoomLevel () const =0
	Returns the current smart zoom level.
virtual PipelineError	enableColorCorrection ()=0
	Enables color correction.
virtual PipelineError	enableColorCorrectionWithReference (const IFrame *referenceFrame)=0
	Enables color grading: generates a color palette from an image and applies it to the video.
virtual PipelineError	enableColorCorrectionWithLutFile (const char *utf8FilePath)=0
	Enables color filtering with a lookup table (LUT).
virtual void	disableColorCorrection ()=0
	Disables color correction.
virtual void	setColorCorrectionPower (float power)=0
	Sets visibility of the color correction effect.
virtual PipelineError	setColorCorrectionParam (ColorCorrectionParam param, float value)=0
	Sets one ColorCorrectionParam of the color correction effect.
virtual float	getColorCorrectionParam (ColorCorrectionParam param, PipelineError *error) const =0
	Returns one ColorCorrectionParam of the color correction effect.
virtual PipelineError	enableLowLightAdjustment ()=0
	Enables the brightening effect.
virtual void	disableLowLightAdjustment ()=0
	Disables the brightening effect.
virtual void	setLowLightAdjustmentPower (float power)=0
	Sets the power of the brightening effect.
virtual float	getLowLightAdjustmentPower () const =0
	Returns the power of the brightening effect.
virtual PipelineError	enableSharpening ()=0
	Enables the sharpening effect.
virtual void	disableSharpening ()=0
	Disables the sharpening effect.
virtual float	getSharpeningPower () const =0
	Returns the current power of the sharpening effect.
virtual void	setSharpeningPower (float power)=0
	Sets the power of the sharpening effect.
virtual PipelineError	enableNoiseSuppression ()=0
	Enables the noise suppression effect, which reduces sensor noise.
virtual void	disableNoiseSuppression ()=0
	Disables the noise suppression effect.
virtual PipelineError	enablePortraitLighting ()=0
	Enables the portrait lighting effect.
virtual void	disablePortraitLighting ()=0
	Disables the portrait lighting effect.
virtual PipelineError	setPortraitLightingParam (PortraitLightingParam param, float value)=0
	Sets one PortraitLightingParam of the portrait lighting effect.
virtual float	getPortraitLightingParam (PortraitLightingParam param, PipelineError *error) const =0
	Returns one PortraitLightingParam of the portrait lighting effect.
virtual IFrame *	process (const IFrame input, PipelineError error)=0
	Processes the frame with all enabled effects applied.
Public Member Functions inherited from tsvb::IRelease
virtual void	release ()=0
	Releases the memory that was allocated for the object.

Detailed Description

Configuration of effects and frame processor.

Created by ISDKFactory::createPipeline(). Use a separate instance for each video stream.

Thread-safe: its methods, except process(), may be called from any thread at any time. process() may be called from any thread too, but not while another process() call is running.

Warning: On Apple platforms, don't release the pipeline from a handler added with addCompletedHandler: or addScheduledHandler: of an MTLCommandBuffer: the release may wait for the pipeline's GPU work, and Metal may run the handlers of all command queues one at a time.

bool initialize(const char* customerID, const char* backgroundPath)
{
    ISDKFactory* factory = createFactory();
    IAuthResult* authResult = factory->auth(customerID, nullptr, nullptr);
    const AuthStatus status = authResult->status();
    authResult->release();
    if (AuthStatus::active != status) {
        // Authorization failed: report the status, the SDK can't be used.
        factory->release();
        return false;
    }
 
    frameFactory = factory->createFrameFactory();
    pipeline = factory->createPipeline();
    factory->release();
 
    pipeline->enableNoiseSuppression();
    pipeline->enableReplaceBackground(&replacementController);
 
    IFrame* background = frameFactory->loadImage(backgroundPath);
    if (nullptr != background) {
        replacementController->setBackgroundImage(background);
        background->release();
    }
    return true;
}
 
void release()
{
    frameFactory->release();
    frameFactory = nullptr;
    replacementController->release();
    replacementController = nullptr;
    pipeline->release();
    pipeline = nullptr;
}

Member Function Documentation

◆ copyConfiguration()

virtual IPipelineConfiguration * tsvb::IPipeline::copyConfiguration ( ) const

pure virtual

Returns a copy of the current configuration. The caller is responsible for releasing it.

◆ copyDefaultConfiguration()

virtual IPipelineConfiguration * tsvb::IPipeline::copyDefaultConfiguration ( ) const

pure virtual

Returns a copy of the default configuration. The caller is responsible for releasing it.

◆ disableBackgroundBlur()

virtual void tsvb::IPipeline::disableBackgroundBlur ( )

pure virtual

Disables background blur.

◆ disableBeautification()

virtual void tsvb::IPipeline::disableBeautification ( )

pure virtual

Disables face beautification.

◆ disableColorCorrection()

virtual void tsvb::IPipeline::disableColorCorrection ( )

pure virtual

Disables color correction.

◆ disableLowLightAdjustment()

virtual void tsvb::IPipeline::disableLowLightAdjustment ( )

pure virtual

Disables the brightening effect.

◆ disableNoiseSuppression()

virtual void tsvb::IPipeline::disableNoiseSuppression ( )

pure virtual

Disables the noise suppression effect.

◆ disablePortraitLighting()

virtual void tsvb::IPipeline::disablePortraitLighting ( )

pure virtual

Disables the portrait lighting effect.

◆ disableReplaceBackground()

virtual void tsvb::IPipeline::disableReplaceBackground ( )

pure virtual

Disables background replacement.

◆ disableSharpening()

virtual void tsvb::IPipeline::disableSharpening ( )

pure virtual

Disables the sharpening effect.

◆ disableSmartZoom()

virtual void tsvb::IPipeline::disableSmartZoom ( )

pure virtual

Disables smart zoom.

◆ enableBeautification()

virtual PipelineError tsvb::IPipeline::enableBeautification ( )

pure virtual

Enables face beautification.

Not available on Backend::CPU: there it returns PipelineErrorCode::notSupportedByBackend.

◆ enableBlurBackground()

virtual PipelineError tsvb::IPipeline::enableBlurBackground ( float blurPower )

pure virtual

Enables background blur.

If already enabled, changes the power of blur.

Parameters

blurPower Power of blur from 0 to 1.

◆ enableColorCorrection()

virtual PipelineError tsvb::IPipeline::enableColorCorrection ( )

pure virtual

Enables color correction.

Automatic, manual or both. In automatic mode it analyzes the frame periodically and corrects colors. Manual settings of ColorCorrectionParam, set with setColorCorrectionParam(), work with it or alone. Disables another enabled color correction effect.

Not available on Backend::CPU: there it returns PipelineErrorCode::notSupportedByBackend.

◆ enableColorCorrectionWithLutFile()

virtual PipelineError tsvb::IPipeline::enableColorCorrectionWithLutFile ( const char * utf8FilePath )

pure virtual

Enables color filtering with a lookup table (LUT).

If already enabled, switches the LUT. Disables another enabled color correction effect.

Parameters

utf8FilePath Path to a .cube file in UTF-8. Only 3D LUTs with maximum size 65 (65x65x65) are supported.

◆ enableColorCorrectionWithReference()

virtual PipelineError tsvb::IPipeline::enableColorCorrectionWithReference ( const IFrame * referenceFrame )

pure virtual

Enables color grading: generates a color palette from an image and applies it to the video.

If already enabled, generates a new color palette from referenceFrame. Disables another enabled color correction effect.

Note: The palette is generated asynchronously: the effect may show a few frames later.

Parameters

referenceFrame The reference to generate a color palette from.

◆ enableLowLightAdjustment()

virtual PipelineError tsvb::IPipeline::enableLowLightAdjustment ( )

pure virtual

Enables the brightening effect.

Low light adjustment enhances the brightness of a dark video. It is useful when the video has a darker environment. It's recommended to use together with color correction.

Not available on Backend::CPU: there it returns PipelineErrorCode::notSupportedByBackend.

◆ enableNoiseSuppression()

virtual PipelineError tsvb::IPipeline::enableNoiseSuppression ( )

pure virtual

Enables the noise suppression effect, which reduces sensor noise.

Not available on Backend::CPU: there it returns PipelineErrorCode::notSupportedByBackend.

◆ enablePortraitLighting()

virtual PipelineError tsvb::IPipeline::enablePortraitLighting ( )

pure virtual

Enables the portrait lighting effect.

Brightens the person and darkens the background around them. The background is darkened only while it is the frame itself, blurred or not. Runs segmentation, the way the background effects do.

Not available on Backend::CPU: there it returns PipelineErrorCode::notSupportedByBackend.

◆ enableReplaceBackground()

virtual PipelineError tsvb::IPipeline::enableReplaceBackground ( IReplacementController ** controller )

pure virtual

Enables background replacement.

By default the background is transparent. A custom background image can be set with IReplacementController::setBackgroundImage(). If background blur is enabled, the custom image is blurred too.

Parameters

controller If not null, receives a new instance of IReplacementController. The caller is responsible for releasing it.

◆ enableSharpening()

virtual PipelineError tsvb::IPipeline::enableSharpening ( )

pure virtual

Enables the sharpening effect.

Sharpening enhances clarity of the video and reduces blurriness.

◆ enableSmartZoom()

virtual PipelineError tsvb::IPipeline::enableSmartZoom ( )

pure virtual

Enables smart zoom. Smart zoom crops around the face.

◆ getBeautificationLevel()

virtual float tsvb::IPipeline::getBeautificationLevel ( ) const

pure virtual

Returns the current beautification level.

◆ getBlurBackgroundState()

virtual bool tsvb::IPipeline::getBlurBackgroundState ( float * blurPower ) const

pure virtual

Returns true if background blur is enabled, otherwise false.

Parameters

blurPower If not null and blur is enabled, receives the blur power.

◆ getColorCorrectionParam()

virtual float tsvb::IPipeline::getColorCorrectionParam	(	ColorCorrectionParam	param,
		PipelineError *	error ) const

pure virtual

Returns one ColorCorrectionParam of the color correction effect.

The value in effect, as setColorCorrectionParam() clamped it, whether or not the effect is enabled.

Parameters

param	The parameter to read.
error	If not null, receives the error code: PipelineErrorCode::invalidArgument if the parameter is unknown.

Returns: The value of the parameter, or 0 on error.

◆ getLowLightAdjustmentPower()

virtual float tsvb::IPipeline::getLowLightAdjustmentPower ( ) const

pure virtual

Returns the power of the brightening effect.

◆ getPortraitLightingParam()

virtual float tsvb::IPipeline::getPortraitLightingParam	(	PortraitLightingParam	param,
		PipelineError *	error ) const

pure virtual

Returns one PortraitLightingParam of the portrait lighting effect.

The value in effect, as setPortraitLightingParam() clamped it, whether or not the effect is enabled.

Parameters

param	The parameter to read.
error	If not null, receives the error code: PipelineErrorCode::invalidArgument if the parameter is unknown.

Returns: The value of the parameter, or 0 on error.

◆ getReplaceBackgroundState()

virtual bool tsvb::IPipeline::getReplaceBackgroundState ( ) const

pure virtual

Returns true if background replacement is enabled, otherwise false.

◆ getSharpeningPower()

virtual float tsvb::IPipeline::getSharpeningPower ( ) const

pure virtual

Returns the current power of the sharpening effect.

◆ getSmartZoomLevel()

virtual float tsvb::IPipeline::getSmartZoomLevel ( ) const

pure virtual

Returns the current smart zoom level.

◆ process()

virtual IFrame * tsvb::IPipeline::process	(	const IFrame *	input,
		PipelineError *	error )

pure virtual

Processes the frame with all enabled effects applied.

Each result depends on the frames processed before it, so pass the frames of a stream one after another, in their order. It may be called from any thread, but not while another process() call is running.

Parameters

input	Frame to process.
error	If not null, receives the error code.

Returns: Processed frame of the input's format, rotation, color range and matrix, or nullptr on error. The caller is responsible for releasing it.

Warning: On Apple platforms, don't call it from a handler added with addCompletedHandler: or addScheduledHandler: of an MTLCommandBuffer: it waits for its own GPU work, its addCompletedHandler: handlers included, and Metal may run the handlers of all command queues one at a time, so the call may wait for itself.

◆ setBeautificationLevel()

virtual void tsvb::IPipeline::setBeautificationLevel ( float level )

pure virtual

Sets the face beautification level.

Parameters

level Level from 0 to 1. Higher number -> more visible effect. Default is 0.48.

◆ setColorCorrectionParam()

virtual PipelineError tsvb::IPipeline::setColorCorrectionParam	(	ColorCorrectionParam	param,
		float	value )

pure virtual

Sets one ColorCorrectionParam of the color correction effect.

The parameters keep their values while the effect is disabled. Out-of-range values are clamped.

// Manual warm look without automatic analysis.
pipeline->enableColorCorrection();
pipeline->setColorCorrectionParam(colorCorrectionParamAutoMode, 0);
pipeline->setColorCorrectionParam(colorCorrectionParamTemperature, 0.3f);
pipeline->setColorCorrectionParam(colorCorrectionParamVibrance, 0.2f);

Parameters

param	The parameter to set.
value	New value of the parameter.

Returns: PipelineErrorCode::invalidArgument if the value is not a finite number or the parameter is unknown.

◆ setColorCorrectionPower()

virtual void tsvb::IPipeline::setColorCorrectionPower ( float power )

pure virtual

Sets visibility of the color correction effect.

An alias of setColorCorrectionParam(colorCorrectionParamPower, power): the two set the same value, and it drives color grading and LUT filtering as well as the correction effect.

Parameters

power Power from 0 to 1. Higher number -> more visible effect.

◆ setConfiguration()

virtual PipelineError tsvb::IPipeline::setConfiguration ( const IPipelineConfiguration * config )

pure virtual

Configures the pipeline, for example whether to use GPU or CPU for processing.

This method is optional. On error the configuration in use stays as it was.

The effects enabled now stay enabled with the new configuration. If the requested backend lacks one of them, for example Backend::CPU while noise suppression is on, the method fails with PipelineErrorCode::enabledUnsupportedFeatures: disable that effect first.

Parameters

config Configuration to apply, see IPipelineConfiguration.

Returns: PipelineErrorCode::ok, or the error code.

◆ setLowLightAdjustmentPower()

virtual void tsvb::IPipeline::setLowLightAdjustmentPower ( float power )

pure virtual

Sets the power of the brightening effect.

Parameters

power Power from 0 to 1. Higher number -> brighter result. Default is 0.8.

◆ setPortraitLightingParam()

virtual PipelineError tsvb::IPipeline::setPortraitLightingParam	(	PortraitLightingParam	param,
		float	value )

pure virtual

Sets one PortraitLightingParam of the portrait lighting effect.

Parameters

param	The parameter to set.
value	Value from 0 to 1. Out-of-range values are clamped.

◆ setSharpeningPower()

virtual void tsvb::IPipeline::setSharpeningPower ( float power )

pure virtual

Sets the power of the sharpening effect.

Parameters

power Power from 0 to 1. Higher number -> sharper result. Default is 0.3.

◆ setSmartZoomLevel()

virtual void tsvb::IPipeline::setSmartZoomLevel ( float level )

pure virtual

Sets the smart zoom level.

Parameters

level Level from 0 to 1. Defines how much area should be filled by the face. Higher number -> more area. Default is 0.8.

The documentation for this class was generated from the following file:

vb_sdk/pipeline.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ copyConfiguration()

◆ copyDefaultConfiguration()

◆ disableBackgroundBlur()

◆ disableBeautification()

◆ disableColorCorrection()

◆ disableLowLightAdjustment()

◆ disableNoiseSuppression()

◆ disablePortraitLighting()

◆ disableReplaceBackground()

◆ disableSharpening()

◆ disableSmartZoom()

◆ enableBeautification()

◆ enableBlurBackground()

◆ enableColorCorrection()

◆ enableColorCorrectionWithLutFile()

◆ enableColorCorrectionWithReference()

◆ enableLowLightAdjustment()

◆ enableNoiseSuppression()

◆ enablePortraitLighting()

◆ enableReplaceBackground()

◆ enableSharpening()

◆ enableSmartZoom()

◆ getBeautificationLevel()

◆ getBlurBackgroundState()

◆ getColorCorrectionParam()

◆ getLowLightAdjustmentPower()

◆ getPortraitLightingParam()

◆ getReplaceBackgroundState()

◆ getSharpeningPower()

◆ getSmartZoomLevel()

◆ process()

◆ setBeautificationLevel()

◆ setColorCorrectionParam()

◆ setColorCorrectionPower()

◆ setConfiguration()

◆ setLowLightAdjustmentPower()

◆ setPortraitLightingParam()

◆ setSharpeningPower()

◆ setSmartZoomLevel()