The videoSource API is for capturing frames from video input devices such as MIPI CSI cameras, V4L2 cameras, video/images files from disk, directories containing a sequence of images, and from RTP/RTSP network video streams over UDP/IP. More...

#include <videoSource.h>

Inheritance diagram for videoSource:

Public Types
enum	Status { ERROR = -2, EOS = -1, TIMEOUT = 0, OK = 1 }
	Stream status codes that are optionally returned from Capture() More...

Public Member Functions
virtual	~videoSource ()
	Destroy interface and release all resources. More...

template<typename T >
bool	Capture (T *image, int status)
	Capture the next image from the video stream, using the default timeout of 1000ms. More...

template<typename T >
bool	Capture (T *image, uint64_t timeout=DEFAULT_TIMEOUT, int status=NULL)
	Capture the next image from the video stream. More...

virtual bool	Capture (void *image, imageFormat format, uint64_t timeout=DEFAULT_TIMEOUT, int status=NULL)=0
	Capture the next image from the video stream. More...

virtual bool	Open ()
	Begin streaming the device. More...

virtual void	Close ()
	Stop streaming the device. More...

bool	IsStreaming () const
	Check if the device is actively streaming or not. More...

uint32_t	GetWidth () const
	Return the width of the stream, in pixels. More...

uint32_t	GetHeight () const
	Return the height of the stream, in pixels. More...

uint32_t	GetFrameRate () const
	Return the framerate, in Hz or FPS. More...

uint64_t	GetFrameCount () const
	Return the number of frames captured. More...

uint64_t	GetLastTimestamp () const
	Get timestamp of the last captured frame, in nanoseconds. More...

imageFormat	GetRawFormat () const
	Get raw image format. More...

const URI &	GetResource () const
	Return the resource URI of the stream. More...

const videoOptions &	GetOptions () const
	Return the videoOptions of the stream. More...

virtual uint32_t	GetType () const
	Return the interface type of the stream. More...

bool	IsType (uint32_t type) const
	Check if this stream is of a particular type. More...

template<typename T >
bool	IsType () const
	Check if a this stream is of a particular type. More...

const char *	TypeToStr () const
	Convert this stream's class type to string. More...

Static Public Member Functions
static videoSource *	Create (const videoOptions &options)
	Create videoSource interface from a videoOptions struct that's already been filled out. More...

static videoSource *	Create (const char *URI, const videoOptions &options=videoOptions())
	Create videoSource interface from a resource URI string and optional videoOptions. More...

static videoSource *	Create (const char *URI, const commandLine &cmdLine)
	Create videoSource interface from a resource URI string and parsing command line arguments. More...

static videoSource *	Create (const char URI, const int argc, char *argv)
	Create videoSource interface from a resource URI string and parsing command line arguments. More...

static videoSource *	Create (const int argc, char **argv, int positionArg=-1)
	Create videoSource interface by parsing command line arguments, including the resource URI. More...

static videoSource *	Create (const commandLine &cmdLine, int positionArg=-1)
	Create videoSource interface by parsing command line arguments, including the resource URI. More...

static const char *	Usage ()
	Usage string for command line arguments to Create() More...

static const char *	TypeToStr (uint32_t type)
	Convert a class type to a string. More...

Static Public Attributes
static const uint64_t	DEFAULT_TIMEOUT =1000
	The default Capture timeout (1000ms) More...

Protected Member Functions
	videoSource (const videoOptions &options)

Protected Attributes
bool	mStreaming

videoOptions	mOptions

uint64_t	mLastTimestamp

imageFormat	mRawFormat

Detailed Description

The videoSource API is for capturing frames from video input devices such as MIPI CSI cameras, V4L2 cameras, video/images files from disk, directories containing a sequence of images, and from RTP/RTSP network video streams over UDP/IP.

videoSource interfaces are implemented by gstCamera, gstDecoder, and imageLoader. The specific implementation is selected at runtime based on the type of resource URI.

videoSource supports the following protocols and resource URI's:

- `csi://0` for MIPI CSI cameras, where `0` can be replaced with the camera port.
It is also assumed that if a number with no protocol is specified (e.g. `"0"`),
this means to use the MIPI CSI camera of that number (`"0"` -> `csi://0`).

- `v4l2:///dev/video0` for V4L2 cameras, where `/dev/video0` can be replaced with
a different video device (e.g. `v4l2:///dev/video1` for V4L2 video device `1`).
If no protocol is specified but the string begins with `/dev/video`, then it is
assumed that the protocol is V4L2 (`/dev/video0` -> `v4l2:///dev/video0`)

- `rtp://@:1234` to recieve an RTP network stream, where `1234` is the port and `@` is shorthand
for localhost. `@` can also be substituted for the IP address of a multicast group.
Note that it is important to manually specify the codec of the stream when using RTP,
as the codec cannot be discovered from the RTP stream itself and need to be provided.
@see videoOptions for more info about the `--input-codec` option.

- `rtsp://username:password@<remote-host>:1234` to subscribe to an RTSP network stream, where
`<remote-host>` should be substituted for the remote host's IP address or hostname, and
`1234` is the port. For example, `rtsp://192.168.1.2:5000`. The `username` and `password`
are optional, and are only used for RTSP streams that require authentication.

- `file:///home/user/my_video.mp4` for disk-based videos, images, and directories of images.
You can leave off the `file://` protocol identifier and it will be deduced from the path.
It can be a relative or absolute path. If a directory is specified that contains images,
those images will be loaded in sequence (sorted alphanumerically). The path can also
contain wildcard characters, for example `"images/*.jpg"` - however when using wildcards
from the command line, enclose the string in quotes otherwise the OS will pre-expand them.
Supported video formats for loading include MKV, MP4, AVI, and FLV. Supported codecs for
decoding include H.264, H.265, VP8, VP9, MPEG-2, MPEG-4, and MJPEG. Supported image formats
for loading include JPG, PNG, TGA, BMP, GIF, PSD, HDR, PIC, and PNM (PPM/PGM binary).

See also: URI for info about resource URI formats.; videoOptions for additional options and command-line arguments.

Member Enumeration Documentation

◆ Status

enum videoSource::Status

Stream status codes that are optionally returned from Capture()

Enumerator
ERROR	an error occurred
EOS	end-of-stream (EOS)
TIMEOUT	a timeout occurred
OK	frame capture successful

Constructor & Destructor Documentation

◆ ~videoSource()

virtual videoSource::~videoSource ( )

virtual

Destroy interface and release all resources.

◆ videoSource()

videoSource::videoSource ( const videoOptions & options )

protected

Member Function Documentation

◆ Capture() [1/3]

template<typename T >

bool videoSource::Capture	(	T **	image,
		int *	status
	)

inline

Capture the next image from the video stream, using the default timeout of 1000ms.

The image formats supported by this templated version of Capture() include the following:

uchar3 (IMAGE_RGB8)
uchar4 (IMAGE_RGBA8)
float3 (IMAGE_RGB32F)
float4 (IMAGE_RGBA32F)

The image format will automatically be deduced from these types. If other types are used with this overload, a static compile-time error will be asserted.

Parameters

[out]	image	output pointer that will be set to the memory containing the image. If this interface has it's videoOptions::zeroCopy flag set to true, the memory was allocated in mapped CPU/GPU memory and is be accessible from both CPU and CUDA. Otherwise, it's accessible only from CUDA.
[out]	status	optional status code returned (

See also: videoSource::Status). -2 on ERROR, -1 on EOS, 0 on TIMEOUT, 1 on OK.

Returns: true if a frame was captured, false if there was an error or a timeout occurred.

◆ Capture() [2/3]

template<typename T >

bool videoSource::Capture	(	T **	image,
		uint64_t	timeout = `DEFAULT_TIMEOUT`,
		int *	status = `NULL`
	)

inline

Capture the next image from the video stream.

The image formats supported by this templated version of Capture() include the following:

uchar3 (IMAGE_RGB8)
uchar4 (IMAGE_RGBA8)
float3 (IMAGE_RGB32F)
float4 (IMAGE_RGBA32F)

The image format will automatically be deduced from these types. If other types are used with this overload, a static compile-time error will be asserted.

Parameters

[out]	image	output pointer that will be set to the memory containing the image. If this interface has it's videoOptions::zeroCopy flag set to true, the memory was allocated in mapped CPU/GPU memory and is be accessible from both CPU and CUDA. Otherwise, it's accessible only from CUDA.
[in]	timeout	timeout in milliseconds to wait to capture the image before returning. The default is 1000ms. A timeout value of `UINT64_MAX` will wait forever. A timeout of 0 will return instantly if a frame wasn't immediately ready.
[out]	status	optional status code returned (

See also: videoSource::Status). -2 on ERROR, -1 on EOS, 0 on TIMEOUT, 1 on OK.

Returns: true if a frame was captured, false if there was an error or a timeout occurred.

◆ Capture() [3/3]

virtual bool videoSource::Capture	(	void **	image,
		imageFormat	format,
		uint64_t	timeout = `DEFAULT_TIMEOUT`,
		int *	status = `NULL`
	)

pure virtual

Capture the next image from the video stream.

The image formats supported by Capture() are IMAGE_RGB8 (uchar3), IMAGE_RGBA8 (uchar4), IMAGE_RGB32F (float3), and IMAGE_RGBA32F (float4).

See also: imageFormat for more info.

Parameters

[out]	image	output pointer that will be set to the memory containing the image. If this interface has it's videoOptions::zeroCopy flag set to true, the memory was allocated in mapped CPU/GPU memory and is be accessible from both CPU and CUDA. Otherwise, it's accessible only from CUDA.
[in]	timeout	timeout in milliseconds to wait to capture the image before returning. The default is 1000ms. A timeout value of `UINT64_MAX` will wait forever. A timeout of 0 will return instantly if a frame wasn't immediately ready.
[out]	status	optional status code returned (

See also: videoSource::Status). -2 on ERROR, -1 on EOS, 0 on TIMEOUT, 1 on OK.

Returns: true if a frame was captured, false if there was an error or a timeout occurred.

Implemented in gstCamera, gstDecoder, and imageLoader.

◆ Close()

virtual void videoSource::Close ( )

virtual

Stop streaming the device.

Note: Close() is automatically called by the videoSource destructor when it gets deleted, so you do not explicitly need to call Close() before exiting the program if you delete your videoSource object.

Reimplemented in gstCamera, gstDecoder, and imageLoader.

◆ Create() [1/6]

static videoSource* videoSource::Create	(	const char *	URI,
		const commandLine &	cmdLine
	)

static

Create videoSource interface from a resource URI string and parsing command line arguments.

See also: videoOptions for valid command-line arguments to be parsed.; the documentation above and the URI struct for more info about resource URI's.

◆ Create() [2/6]

static videoSource* videoSource::Create	(	const char *	URI,
		const int	argc,
		char **	argv
	)

static

Create videoSource interface from a resource URI string and parsing command line arguments.

See also: videoOptions for valid command-line arguments to be parsed.; the documentation above and the URI struct for more info about resource URI's.

◆ Create() [3/6]

static videoSource* videoSource::Create	(	const char *	URI,
		const videoOptions &	options = `videoOptions()`
	)

static

Create videoSource interface from a resource URI string and optional videoOptions.

See also: the documentation above and the URI struct for more info about resource URI's.

◆ Create() [4/6]

static videoSource* videoSource::Create	(	const commandLine &	cmdLine,
		int	positionArg = `-1`
	)

static

Create videoSource interface by parsing command line arguments, including the resource URI.

Parameters

positionArg indicates the positional argument number in the command line of the resource URI (or -1 if a positional argument isn't used, and should instead be parsed from the --input= option).

See also: videoOptions for valid command-line arguments to be parsed.; the documentation above and the URI struct for more info about resource URI's.

◆ Create() [5/6]

static videoSource* videoSource::Create	(	const int	argc,
		char **	argv,
		int	positionArg = `-1`
	)

static

Create videoSource interface by parsing command line arguments, including the resource URI.

Parameters

positionArg indicates the positional argument number in the command line of the resource URI (or -1 if a positional argument isn't used, and should instead be parsed from the --input= option).

See also: videoOptions for valid command-line arguments to be parsed.; the documentation above and the URI struct for more info about resource URI's.

◆ Create() [6/6]

static videoSource* videoSource::Create ( const videoOptions & options )

static

Create videoSource interface from a videoOptions struct that's already been filled out.

It's expected that the supplied videoOptions already contain a valid resource URI.

◆ GetFrameCount()

uint64_t videoSource::GetFrameCount ( ) const

inline

Return the number of frames captured.

◆ GetFrameRate()

uint32_t videoSource::GetFrameRate ( ) const

inline

Return the framerate, in Hz or FPS.

◆ GetHeight()

uint32_t videoSource::GetHeight ( ) const

inline

Return the height of the stream, in pixels.

◆ GetLastTimestamp()

uint64_t videoSource::GetLastTimestamp ( ) const

inline

Get timestamp of the last captured frame, in nanoseconds.

◆ GetOptions()

const videoOptions& videoSource::GetOptions ( ) const

inline

Return the videoOptions of the stream.

◆ GetRawFormat()

imageFormat videoSource::GetRawFormat ( ) const

inline

Get raw image format.

◆ GetResource()

const URI& videoSource::GetResource ( ) const

inline

Return the resource URI of the stream.

◆ GetType()

virtual uint32_t videoSource::GetType ( ) const

inlinevirtual

Return the interface type of the stream.

This could be one of the following values:

Reimplemented in gstCamera, gstDecoder, and imageLoader.

◆ GetWidth()

uint32_t videoSource::GetWidth ( ) const

inline

Return the width of the stream, in pixels.

◆ IsStreaming()

bool videoSource::IsStreaming ( ) const

inline

Check if the device is actively streaming or not.

Returns: true if the device is streaming (open), or false if it's closed or has reached EOS (End Of Stream).

◆ IsType() [1/2]

template<typename T >

bool videoSource::IsType ( ) const

inline

Check if a this stream is of a particular type.

Can be used with gstCamera, gstDecoder, and imageLoader. For example:

if( stream->IsType<gstCamera>() ) gstCamera* camera = (gstCamera*)stream; // safe to cast

◆ IsType() [2/2]

bool videoSource::IsType ( uint32_t type ) const

inline

Check if this stream is of a particular type.

See also: GetType() for possible values.

◆ Open()

virtual bool videoSource::Open ( )

virtual

Begin streaming the device.

After Open() is called, frames from the device will begin to be captured.

Open() is not stricly necessary to call, if you call one of the Capture() functions they will first check to make sure that the stream is opened, and if not they will open it automatically for you.

Returns: true on success, false if an error occurred opening the stream.

Reimplemented in gstCamera, gstDecoder, and imageLoader.

◆ TypeToStr() [1/2]

const char* videoSource::TypeToStr ( ) const

inline

Convert this stream's class type to string.

◆ TypeToStr() [2/2]

static const char* videoSource::TypeToStr ( uint32_t type )

static

Convert a class type to a string.

◆ Usage()

static const char* videoSource::Usage ( )

inlinestatic

Usage string for command line arguments to Create()

Member Data Documentation

◆ DEFAULT_TIMEOUT

const uint64_t videoSource::DEFAULT_TIMEOUT =1000

static

The default Capture timeout (1000ms)

◆ mLastTimestamp

uint64_t videoSource::mLastTimestamp

protected

◆ mOptions

videoOptions videoSource::mOptions

protected

◆ mRawFormat

imageFormat videoSource::mRawFormat

protected

◆ mStreaming

bool videoSource::mStreaming

protected

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

jetson-utils/videoSource.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Status

Constructor & Destructor Documentation

◆ ~videoSource()

◆ videoSource()

Member Function Documentation

◆ Capture() [1/3]

◆ Capture() [2/3]

◆ Capture() [3/3]

◆ Close()

◆ Create() [1/6]

◆ Create() [2/6]

◆ Create() [3/6]

◆ Create() [4/6]

◆ Create() [5/6]

◆ Create() [6/6]

◆ GetFrameCount()

◆ GetFrameRate()

◆ GetHeight()

◆ GetLastTimestamp()

◆ GetOptions()

◆ GetRawFormat()

◆ GetResource()

◆ GetType()

◆ GetWidth()

◆ IsStreaming()

◆ IsType() [1/2]

◆ IsType() [2/2]

◆ Open()

◆ TypeToStr() [1/2]

◆ TypeToStr() [2/2]

◆ Usage()

Member Data Documentation

◆ DEFAULT_TIMEOUT

◆ mLastTimestamp

◆ mOptions

◆ mRawFormat

◆ mStreaming