API Documentation

Video

The PolySync Video API provides an interface for image devices, encoder/decoder, and utilities. In Linux, this uses a mixture of V4l2 and GStreamer.

Usage #include <PolySyncVideo.hpp>

API Functions

The following Video API functions do not belong to a class.

std::vector< VideoDevice > getAvailableVideoDevices ( )

This function will be used to check the host machine for connected video devices.

Returns
  • std::vector< VideoDevice > - Array of video devices on host machine

VideoDevice

The VideoDevice class provides an interface for polling data from an image data sensor connected to the system.

Example:

try
{
    auto deviceList = polysync::getAvailableVideoDevices();
    for( auto device : deviceList )
    {
        device.open();
        device.enableStreaming();
        if( device.poll() )
        {
            auto videoFrame = device.getBuffer();
            //do something with the frame
        }
        device.close()
    }
}
catch( polysync::DTCException & e )
{
    std::cout << e.what() << std::endl;
    //backup plan here...
}

VideoDevice::VideoDevice ( … )

The VideoDevice constructor will create a video device if one exists by the given name on the host.

Parameters
in/out type name description
std::string deviceName The name of device as represented on the host, e.g. on Linux “/dev/video0.”
Exceptions
  • Throws polysync::DTCException on failure:

VideoDevice::VideoDevice ( … )

The VideoDevice constructor will be used by getAvailableVideoDevices.

Parameters
in/out type name description
in ps_video_device & device C-struct used by PolySync.
Exceptions
  • Throws polysync::DTCException on failure:

VideoDevice::~VideoDevice ( )

The destructor closes the connection to the image data device.

std::string VideoDevice::getName ( )

Returns
  • std::string - Representation for name of the device, e.g. in Linux, “/dev/video0.”

std::string VideoDevice::getType ( )

This most often represents the device card type, i.e. ‘HD Pro Webcam C920’.

Returns
  • std::string - Representation for video device type

VideoDevice::getHandle ( )

This will get the device handle.

In Linux, this is the device file descriptor.

Returns

VideoDevice::getFrameSize ( )

Returns
  • ulong - Size of the device data buffer [bytes]

std::vector< uchar > VideoDevice::getFrame ( )

Returns
  • std::vector< uchar > - Copy of the device data buffer; empty vector is possible

std::vector< ps_pixel_format_kind > VideoDevice::getAvailablePixelFormats ( )

This will get the list of pixel formats supported by this device.

Returns
Exceptions
  • Throws polysync::DTCException on failure:

VideoDevice::formatIsSupported ( … )

This function will check if a device will accept the given VideoFormat configuration.

Parameters
in/out type name description
in VideoFormat format Object containing desired width, height, and ps_pixel_format_kind.
Returns
  • bool - True if format is supported
Exceptions
  • Throws polysync::DTCException on failure:

VideoDevice::setFormat ( … )

This will set the output format for the video device.

Image width [pixels], image height [pixels], pixel format ( e.g. PIXEL_FORMAT_MJPEG ), and data rate [frames per second].

Parameters
in/out type name description
in VideoFormat format Object containing desired width, height, ps_pixel_format_kind, and frames per second.
Returns
  • bool - True on success
Exceptions
  • Throws polysync::DTCException on failure:

VideoDevice::setFrameRate ( … )

This function will apply the video device frame rate settings.

Parameters
in/out type name description
in ulong framesPerSecond The desired number of frames per second. [N frames / 1 second]
Returns
  • bool - False if framesPerSecond is not supported, true if success
Exceptions
  • Throws polysync::DTCException on failure:

VideoDevice::enableStreaming ( )

This will begin the data capture for the connected image data device.

Exceptions

VideoDevice::poll ( … )

This will poll for data from this device.

Parameters
in/out type name description
in ps_timestamp timeout = 0 Length of time to wait for the poll. The default of 0 will block this function until the data is received. [microseconds]
Returns
  • False if the data not available; otherwise, return is true
Exceptions
  • Throws polysync::DTCException on failure:

VideoEncoder

The VideoEncoder class provides convenience for encoding raw video frame data.

VideoEncoder::VideoEncoder ( … )

The VideoEncoder constructor will create a video encoder for decoding raw video frames.

Parameters
in/out type name description
in VideoFormat inputFormat The raw video frame format to encode.
out VideoFormat outputFormat The format of encoded output.
Exceptions
  • Throws polysync::DTCException on failure:

VideoEncoder::~VideoEncoder ( … )

The destructor will release resources used by an encoder.

VideoEncoder::encode ( … )

This will encode new data to the specification provide to the constructor.

Parameters
in/out type name description
in const std::vector< uchar > & frameBuffer The raw video frame to encode. Output is in the format given to the constructor.
Exceptions
  • Throws polysync::DTCException on failure:

std::vector< uchar > VideoEncoder::getCopyOfEncodedBuffer ( )

Returns
  • std::vector< uchar > Copy of the encoded video frame data

VideoDecoder

The VideoDecoder convenience class for decoding an encoded video frame.

VideoDecoder::VideoDecoder ( … )

The VideoDecoder constructor initializes a video decoder for decoding video frames.

Parameters
in/out type name description
in VideoFormat inputFormat Format of data input to the decoder.
in VideoFormat outputFormat Format of data output by the decoder.
Exceptions
  • Throws polysync::DTCException on failure:

VideoDecoder::~VideoDecoder ( )

The destructor will release resources used by an encoder.

VideoDecoder::decode ( … )

This will decode new data to the output format provided to the constructor.

Parameters
in/out type name description
in const std::vector< uchar > & frameBuffer The video frame data to decode.
Exceptions
  • Throws polysync::DTCException on failure:

std::vector< uchar > VideoDecoder::getCopyOfDecodedBuffer ( … )

Parameters
in/out type name description
largest The largest size to copy.
Returns
  • Copy of decoded buffer

VideoFormat

The VideoFormat class represents the format of video frame data using: pixel format, frame width, frame height, and frames-per-second.

VideoFormat::VideoFormat ( )

VideoFormat::VideoFormat ( … )

This function describes the format of a video frame buffer, used by VideoDevice, VideoEncoder, and VideoDecoder to describe image data device input/output.

Parameters
in/out type name description
in ps_pixel_format_kind pixelFormat Raw, encoded, or decoded pixel format. Example: PIXEL_FORMAT_MJPEG.
in ulong pixelWidth Horizontal frame size. [pixels]
in ulong pixelHeight Vertical frame size. [pixels]
in ulong framesPerSecond Data rate.

VideoFormat::getFramesPerSecond ( )

An accessor for a private member.

Returns
  • ulong - _framesPerSecond

VideoFormat::getHeight ( )

An accessor for a private member.

Returns
  • ulong - _height

VideoFormat::getPixelFormat ( )

An accessor for a private member.

Returns
  • ulong - _pixelFormat

VideoFormat::getWidth ( )

An accessor for a private member.

Returns
  • ulong - _width

VideoFormat::setFramesPerSecond ( … )

A mutator for a private member

Parameters
in/out type name description
in ulong ‘framesPerSecond’ Value to set.

VideoFormat::setHeight ( … )

A mutator for a private member.

Parameters
in/out type name description
in ulong ‘pixelHeight’ Value to set.

VideoFormat::setPixelFormat ( … )

A mutator for a private member.

Parameters
in/out type name description
in ulong ‘pixelFormat’ Value to set.

VideoFormat::setWidth ( … )

A mutator for a private member.

Parameters
in/out type name description
in ulong ‘pixelWidth’ Value to set.