A class to represent a video frame. More...

#include <videoframe.h>

Public Member Functions
	VideoFrame (enum ColourSpace colour, bool manage_data=false)
	Constructor that by default will use externally managed frame data. More...

	VideoFrame (enum ColourSpace colour, size_t cols, size_t rows, size_t stereo_count=1)
	Allocates memory for specified dimensions, and sets all pixels to black. More...

	VideoFrame (const VideoFrame &rhs)
	Create a video frame by copying the data and all properties of `rhs`. More...

virtual	~VideoFrame ()
	Destructor that will free allocated data in case data management is set. More...

void	operator= (const VideoFrame &rhs)
	Clone `rhs`, copying its data. More...

void	init_from_specs (unsigned char *data, size_t data_length, size_t cols, size_t rows, size_t stereo_count=1)
	Initialise using passed data AND frame specs. More...

const size_t	data_length (size_t stereo_index=0) const
	Get length of data buffer. More...

size_t	stereo_count () const
	Get number of stereo frames stored in this object. More...

size_t	rows () const
	Get number of rows (y-axis, i.e. height) More...

size_t	cols () const
	Get number of columns (x-axis, i.e. width) More...

bool	manages_own_data () const
	Get whether data is managed by this object or externally. More...

unsigned char *const	data (size_t stereo_index=0) const
	Get a pointer to frame data. More...

enum ColourSpace	colour () const
	Get what colour space `this` frame uses. More...

Static Public Member Functions
static size_t	required_data_length (enum ColourSpace colour, size_t cols, size_t rows)
	Compute how much memory is needed to accommodate a video frame in `colour` space with `cols` and `rows` dimensions. More...

static size_t	required_pixel_length (enum ColourSpace colour)
	Get the pixel depth in number of bits for `colour`. More...

Protected Member Functions
	VideoFrame ()
	Default constructor that should never be called externally. More...

void	clone (const VideoFrame &rhs)
	Clone `rhs`, after setting `_manage_data`. More...

void	set_dimensions (size_t cols, size_t rows)
	Set dimensions in conjunction with colour space requirements. More...

void	allocate_memory (size_t data_length)
	Allocate / extend memory and set data length indicator, ONLY IF managing own data. More...

void	free_memory ()
	Free any managed memory, and set all spec variables to 0 or `nullptr`. More...

void	set_pixels_black ()
	Set all pixels of frame to black. More...

void	validate_stereo_index (size_t stereo_index) const

Protected Attributes
enum ColourSpace	_colour
	Colour space, i.e. description of contained data. More...

unsigned char *	_data
	Frame data. More...

size_t	_data_length
	Frame data length. More...

size_t	_stereo_count
	Number of stereo frames stored, i.e. the total number of frames. More...

size_t	_rows
	Always use `set_dimensions()` to set this. More...

size_t	_cols
	Always use `set_dimensions()` to set this. More...

bool	_manage_data

Detailed Description

A class to represent a video frame.

For efficiency issues, data can be chosen to not be copied. In that case, the caller is responsible for ensuring the data pointer is valid during the lifetime of the frame object.

Stereo frame data from a particular point in time are included within a single frame object, so as to preserve temporal relations and to facilitate potential stereo encoding.

Constructor & Destructor Documentation

§ VideoFrame() [1/4]

gg::VideoFrame::VideoFrame ( )

protected

Default constructor that should never be called externally.

§ VideoFrame() [2/4]

gg::VideoFrame::VideoFrame	(	enum ColourSpace	colour,
		bool	manage_data = `false`
	)

Constructor that by default will use externally managed frame data.

The frame can later be initialised by init_from_specs()

Parameters

colour
manage_data

See also: init_from_specs

§ VideoFrame() [3/4]

gg::VideoFrame::VideoFrame	(	enum ColourSpace	colour,
		size_t	cols,
		size_t	rows,
		size_t	stereo_count = `1`
	)

Allocates memory for specified dimensions, and sets all pixels to black.

cols and rows are checked in conjunction with colour requirements. I420 requires even dimensions, so in case an odd dimension is provided, it is made even by adding a pixel.

Parameters

colour
cols
rows
stereo_count	if larger than 1, then this frame will keep the specified number of stereo frames

§ VideoFrame() [4/4]

gg::VideoFrame::VideoFrame ( const VideoFrame & rhs )

Create a video frame by copying the data and all properties of rhs.

Attention: In Python: This constructor is not available yet.

Parameters

rhs

§ ~VideoFrame()

gg::VideoFrame::~VideoFrame ( )

virtual

Destructor that will free allocated data in case data management is set.

See also: manages_own_data

Member Function Documentation

§ allocate_memory()

void gg::VideoFrame::allocate_memory ( size_t data_length )

protected

Allocate / extend memory and set data length indicator, ONLY IF managing own data.

Parameters

data_length passed to avoid allocating in case existing memory satisfies the length requirement

See also: _data; _data_length; _manage_data

§ clone()

void gg::VideoFrame::clone ( const VideoFrame & rhs )

protected

Clone rhs, after setting _manage_data.

Parameters

rhs

See also: _manage_data

§ colour()

enum ColourSpace gg::VideoFrame::colour ( ) const

inline

Get what colour space this frame uses.

Returns

§ cols()

size_t gg::VideoFrame::cols ( ) const

inline

Get number of columns (x-axis, i.e. width)

Returns

§ data()

unsigned char *const gg::VideoFrame::data ( size_t stereo_index = 0 ) const

Get a pointer to frame data.

The pointer itself cannot be re-assigned, i.e. the data storage location cannot be changed. However the contents of the storage, i.e. the raw video data can be modified. Although this might be considered against the encapsulation principle, this interface is provided considering real-time image processing pipelines where creating copies of the video data could degrade performance.

Attention: In Python: This function is available only when NumPy support is enabled. It can be used to access video data as NumPy arrays. The signature is different as well:

flat_arr = frame.data(False) # False => flat NumPy array
# flat_arr.shape => (frame.data_length(),)
# structured NumPy arrays currently available only from BGRA frames
if frame.colour() == ColourSpace.BGRA:
    struc_arr = frame.data(True) # True => structured NumPy array
    # struc_arr.shape => (frame.rows(), frame.cols(), 4)
# stereo index is the second (optional) parameter to this
# function in Python, e.g:
struc_arr_of_2nd_stereo_frame = frame.data(True, 1)
# the following calls are equivalent
frame.data() == frame.data(False)
frame.data() == frame.data(False, 0)
frame.data(True) == frame.data(True, 0)

Parameters

stereo_index index of requested stereo frame

Exceptions

std::out_of_range if provided index value is invalid (i.e. out of range)

Returns

See also: VideoFrame(const VideoFrame & rhs)

§ data_length()

const size_t gg::VideoFrame::data_length ( size_t stereo_index = 0 ) const

Get length of data buffer.

Parameters

stereo_index index of stereo frame whose length is requested

Exceptions

std::out_of_range if provided index value is invalid (i.e. out of range)

Returns

§ free_memory()

void gg::VideoFrame::free_memory ( )

protected

Free any managed memory, and set all spec variables to 0 or nullptr.

See also: _manage_data; _data; _data_length; _cols; _rows

§ init_from_specs()

void gg::VideoFrame::init_from_specs	(	unsigned char *	data,
		size_t	data_length,
		size_t	cols,
		size_t	rows,
		size_t	stereo_count = `1`
	)

Initialise using passed data AND frame specs.

The caller is responsible for ensuring consistency of specs. As such, the only check performed is whether the columns and rows are in line with the frame's colour space requirements. Other than that, this function proceeds BLINDLY. So use with care.

Attention: In Python: This function is not available yet.

Parameters

data
data_length	in case of stereo frames, this is the total length of passed data buffer. Only stereo frames with exactly the same dimensions are supports, so this is assumed to be divisible by the number of stereo frames.
cols	the width of a single video frame
rows	the height of a single video frame
stereo_count	the number of stereo frames included in passed data

See also: manages_own_data; VideoFrame(enum ColourSpace, size_t, size_t)

§ manages_own_data()

bool gg::VideoFrame::manages_own_data ( ) const

inline

Get whether data is managed by this object or externally.

Attention: In Python: This function is not available yet.

Returns

§ operator=()

void gg::VideoFrame::operator= ( const VideoFrame & rhs )

Clone rhs, copying its data.

Attention: In Python: This function is not available yet.

Parameters

rhs

§ required_data_length()

size_t gg::VideoFrame::required_data_length	(	enum ColourSpace	colour,
		size_t	cols,
		size_t	rows
	)

static

Compute how much memory is needed to accommodate a video frame in colour space with cols and rows dimensions.

Parameters

colour
cols
rows

Exceptions

BasicException if cols or rows are 0 or colour is not supported

§ required_pixel_length()

size_t gg::VideoFrame::required_pixel_length ( enum ColourSpace colour )

static

Get the pixel depth in number of bits for colour.

Parameters

colour

Returns

Exceptions

BasicException if colour not supported

§ rows()

size_t gg::VideoFrame::rows ( ) const

inline

Get number of rows (y-axis, i.e. height)

Returns

§ set_dimensions()

void gg::VideoFrame::set_dimensions	(	size_t	cols,
		size_t	rows
	)

protected

Set dimensions in conjunction with colour space requirements.

Parameters

cols
rows

See also: VideoFrame(enum ColourSpace, size_t, size_t)

§ set_pixels_black()

void gg::VideoFrame::set_pixels_black ( )

protected

Set all pixels of frame to black.

§ stereo_count()

size_t gg::VideoFrame::stereo_count ( ) const

inline

Get number of stereo frames stored in this object.

Returns

§ validate_stereo_index()

void gg::VideoFrame::validate_stereo_index ( size_t stereo_index ) const

inlineprotected

Parameters

stereo_index

Exceptions

std::out_of_range if passed stereo index is invalid

Member Data Documentation

§ _colour

enum ColourSpace gg::VideoFrame::_colour

protected

Colour space, i.e. description of contained data.

§ _cols

size_t gg::VideoFrame::_cols

protected

Always use set_dimensions() to set this.

See also: cols(); set_dimensions()

§ _data

unsigned char* gg::VideoFrame::_data

protected

Frame data.

§ _data_length

size_t gg::VideoFrame::_data_length

protected

Frame data length.

§ _manage_data

bool gg::VideoFrame::_manage_data

protected

See also: manages_own_data()

§ _rows

size_t gg::VideoFrame::_rows

protected

Always use set_dimensions() to set this.

See also: rows(); set_dimensions()

§ _stereo_count

size_t gg::VideoFrame::_stereo_count

protected

Number of stereo frames stored, i.e. the total number of frames.

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

src/api/videoframe.h
src/api/videoframe.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

§ VideoFrame() [1/4]

§ VideoFrame() [2/4]

§ VideoFrame() [3/4]

§ VideoFrame() [4/4]

§ ~VideoFrame()

Member Function Documentation

§ allocate_memory()

§ clone()

§ colour()

§ cols()

§ data()

§ data_length()

§ free_memory()

§ init_from_specs()

§ manages_own_data()

§ operator=()

§ required_data_length()

§ required_pixel_length()

§ rows()

§ set_dimensions()

§ set_pixels_black()

§ stereo_count()

§ validate_stereo_index()

Member Data Documentation

§ _colour

§ _cols

§ _data

§ _data_length

§ _manage_data

§ _rows

§ _stereo_count