Frame< A > Struct Template Reference

The Frame structure provides storage and manipulation of frames (multiplanar images). More...

#include <SimdFrame.hpp>

Public Types
enum	Format {   None = 0 ,   Nv12 ,   Yuv420p ,   Bgra32 ,   Bgr24 ,   Gray8 ,   Rgb24 ,   Rgba32 ,   Yuv444p ,   Lab24 }
typedef A< uint8_t >	Allocator
typedef void(*	DeleterPtr) (void *context)

Public Member Functions
	Frame ()
	Frame (const Frame &frame)
	Frame (Frame &&frame) noexcept
	Frame (const View< A > &view, bool flipped_=false, double timestamp_=0)
	Frame (View< A > &&view, bool flipped_=false, double timestamp_=0)
	Frame (size_t width_, size_t height_, Format format_, bool flipped_=false, double timestamp_=0, SimdYuvType yuvType_=SimdYuvUnknown)
	Frame (const Point< ptrdiff_t > &size, Format format_, bool flipped_=false, double timestamp_=0, SimdYuvType yuvType_=SimdYuvUnknown)
	Frame (size_t width_, size_t height_, Format format_, uint8_t *data0, size_t stride0, uint8_t *data1, size_t stride1, uint8_t *data2, size_t stride2, bool flipped_=false, double timestamp_=0, SimdYuvType yuvType_=SimdYuvUnknown, DeleterPtr deleter=NULL, void *context=NULL)
	~Frame ()
Frame *	Clone () const
Frame *	Clone (const Rectangle< ptrdiff_t > &rect) const
Frame *	Clone (Frame &buffer) const
Frame	Copy () const
Frame	Copy (const Rectangle< ptrdiff_t > &rect) const
Frame &	operator= (const Frame &frame)
Frame &	operator= (Frame &&frame)
Frame &	Ref ()
void	Recreate (size_t width_, size_t height_, Format format_, SimdYuvType yuvType_=SimdYuvUnknown)
void	Recreate (const Point< ptrdiff_t > &size, Format format_, SimdYuvType yuvType_=SimdYuvUnknown)
Frame	Region (const ptrdiff_t &left, const ptrdiff_t &top, const ptrdiff_t &right, const ptrdiff_t &bottom) const
Frame	Region (ptrdiff_t &left, ptrdiff_t &top, ptrdiff_t &right, ptrdiff_t &bottom) const
Frame	Region (const Point< ptrdiff_t > &topLeft, const Point< ptrdiff_t > &bottomRight) const
Frame	Region (Point< ptrdiff_t > &topLeft, Point< ptrdiff_t > &bottomRight) const
Frame	Region (const Rectangle< ptrdiff_t > &rect) const
Frame	Region (Rectangle< ptrdiff_t > &rect) const
Frame	Flipped () const
Point< ptrdiff_t >	Size () const
size_t	DataSize () const
size_t	Area () const
size_t	PlaneCount () const
void	Clear ()
void	Swap (Frame &other)
bool	Owner () const
void	Capture ()

Static Public Member Functions
static size_t	PlaneCount (Format format)

Data Fields
const size_t	width
	A width of the frame in pixels (luma / full-frame size).
const size_t	height
	A height of the frame in pixels (luma / full-frame size).
const Format	format
	A pixel format of the frame.
View< A >	planes [PLANE_COUNT_MAX]
	Image planes of the frame. Used entries are [0, PlaneCount()). Packed formats store the image in planes[0].
bool	flipped
	A flag of a vertically flipped image (false - point (0, 0) is at the top-left corner, true - point (0, 0) is at the bottom-left corner). Compatible() and Convert() require the same value.
double	timestamp
	A timestamp of the frame. Typical usage stores time in seconds (for example OpenCV CAP_PROP_POS_MSEC * 0.001).
const SimdYuvType	yuvType
	A YUV color space of YUV formats. Defaults to SimdYuvBt601 for Nv12, Yuv420p and Yuv444p. Packed formats use SimdYuvUnknown.

Static Public Attributes
static const size_t	PLANE_COUNT_MAX = 4

Detailed Description

template<template< class > class A>
struct Simd::Frame< A >

The Frame structure provides storage and manipulation of frames (multiplanar images).

The structure holds one or more Simd::View planes that together form a video frame. Packed formats (Gray8, Bgr24, Bgra32, Rgb24, Rgba32, Lab24) use planes[0]. Nv12 uses two planes (full-size Y and half-size interleaved UV). Yuv420p uses three planes (full-size Y and half-size U, V). Yuv444p uses three full-size Y, U, V planes.

A typical usage wraps a packed Simd::View (or an OpenCV cv::Mat through View) as a Frame with a timestamp, converts it to YUV, optionally resizes it, and converts it back. Simd::Motion::Detector::NextFrame takes Frame as input. Packed output is drawn or saved through planes[0].

Copy constructor and assignment create a reference to the same planes (not a deep copy). Use Copy() or Clone() to duplicate pixel data. Ref() is used to pass a temporary Frame as a non-const reference, for example to Simd::Convert.

Nv12 and Yuv420p require even width and height. For YUV formats yuvType defaults to SimdYuvBt601 when it is SimdYuvUnknown. Packed formats set yuvType to SimdYuvUnknown.

Using example:

#include "Simd/SimdFrame.hpp"
 
int main()
{
    typedef Simd::View<Simd::Allocator> View;
    typedef Simd::Frame<Simd::Allocator> Frame;
    typedef Simd::Point<ptrdiff_t> Size;
 
    View image(320, 240, View::Bgr24);
    Frame input(image, false, 0.040);
 
    Frame yuv(input.Size(), Frame::Yuv420p);
    Simd::Convert(input, yuv);
 
    Frame resized;
    Simd::Resize(yuv, resized, Size(160, 120), SimdResizeMethodBilinear);
 
    Frame rgb(resized.Size(), Frame::Rgb24);
    Simd::Convert(resized, rgb);
 
    rgb.planes[0].Save("frame.ppm");
 
    return 0;
}

Related Functions.

Member Typedef Documentation

Allocator

typedef A<uint8_t> Allocator

Allocator type definition.

DeleterPtr

typedef void(* DeleterPtr) (void *context)

Optional callback called from the destructor with context when the Frame wraps an external buffer.

Member Enumeration Documentation

Format

enum Format

Describes pixel format types of a frame.

PlaneCount() returns how many entries of planes[] are used. Nv12 and Yuv420p store chroma at half width and half height and require even frame width and height.

Enumerator
None	An undefined pixel format. PlaneCount is 0.
Nv12	Two planes: planes[0] is 8-bit full-size Y (View::Gray8), planes[1] is 16-bit interleaved half-size UV (View::Uv16). Width and height must be even.
Yuv420p	Three planes: planes[0] is 8-bit full-size Y, planes[1] and planes[2] are 8-bit half-size U and V (View::Gray8). Width and height must be even.
Bgra32	One plane 32-bit (4 8-bit channels) BGRA (Blue, Green, Red, Alpha) pixel format in planes[0].
Bgr24	One plane 24-bit (3 8-bit channels) BGR (Blue, Green, Red) pixel format in planes[0].
Gray8	One plane 8-bit gray pixel format in planes[0].
Rgb24	One plane 24-bit (3 8-bit channels) RGB (Red, Green, Blue) pixel format in planes[0].
Rgba32	One plane 32-bit (4 8-bit channels) RGBA (Red, Green, Blue, Alpha) pixel format in planes[0].
Yuv444p	Three planes: planes[0], planes[1] and planes[2] are 8-bit full-size Y, U, V (View::Gray8).
Lab24	One plane 24-bit (3 8-bit channels) Lab (CIELAB) pixel format in planes[0].

Constructor & Destructor Documentation

Frame() [1/8]

SIMD_INLINE Frame

Creates a new empty Frame structure.

Width and height are 0, format is None, yuvType is SimdYuvUnknown, flipped is false and timestamp is 0.

Frame() [2/8]

SIMD_INLINE Frame

(

const Frame< A > &

frame

)

Creates a new Frame structure on the base of the other frame.

Note

This constructor does not create a new frame! It only creates a reference to the same planes. If you want to create a copy then must use method Simd::Frame::Copy or Simd::Frame::Clone.

Parameters

[in]

frame

- an original frame.

Frame() [3/8]

SIMD_INLINE Frame ( Frame< A > &&  frame )

noexcept

Move constructor of Frame structure.

Transfers planes and the optional deleter from frame. After the call frame is empty.

Parameters

[in]

frame

- a moved Frame.

Frame() [4/8]

SIMD_INLINE Frame	(	const View< A > &	view,
		bool	flipped_ = false,
		double	timestamp_ = 0
	)

Creates a new one-plane Frame structure on the base of the image view.

Supported view formats are View::Gray8, View::Bgr24, View::Bgra32, View::Rgb24, View::Rgba32 and View::Lab24. Other formats assert. yuvType is set to SimdYuvUnknown.

Typical usage wraps a video image (or an OpenCV cv::Mat through View) together with a timestamp before Simd::Convert or Motion::Detector::NextFrame.

Note

This constructor does not create a new image frame! It only creates a reference to the same image. If you want to create a copy then must use method Simd::Frame::Copy or Simd::Frame::Clone.

Parameters

[in]	view	- an original image view.
[in]	flipped_	- a flag of a vertically flipped image of the created frame. It is equal to false by default.
[in]	timestamp_	- a timestamp of the created frame. It is equal to 0 by default.

Frame() [5/8]

SIMD_INLINE Frame	(	View< A > &&	view,
		bool	flipped_ = false,
		double	timestamp_ = 0
	)

Creates a new one-plane Frame structure on the base of the temporary image view.

Supported view formats are the same as for the const View constructor. The view is moved into planes[0].

Parameters

[in]	view	- a temporary image view.
[in]	flipped_	- a flag of a vertically flipped image of the created frame. It is equal to false by default.
[in]	timestamp_	- a timestamp of the created frame. It is equal to 0 by default.

Frame() [6/8]

SIMD_INLINE Frame	(	size_t	width_,
		size_t	height_,
		Format	format_,
		bool	flipped_ = false,
		double	timestamp_ = 0,
		SimdYuvType	yuvType_ = SimdYuvUnknown
	)

Creates a new Frame structure with specified width, height and pixel format.

Allocates owned planes for format_. Nv12 and Yuv420p require even width and height. For YUV formats yuvType_ equal to SimdYuvUnknown is replaced by SimdYuvBt601. Packed formats set yuvType to SimdYuvUnknown.

Parameters

[in]	width_	- a width of created frame.
[in]	height_	- a height of created frame.
[in]	format_	- a pixel format of created frame.
[in]	flipped_	- a flag of a vertically flipped image of the created frame. It is equal to false by default.
[in]	timestamp_	- a timestamp of the created frame. It is equal to 0 by default.
[in]	yuvType_	- a YUV format type of the created frame. It is equal to SimdYuvUnknown by default.

Frame() [7/8]

SIMD_INLINE Frame	(	const Point< ptrdiff_t > &	size,
		Format	format_,
		bool	flipped_ = false,
		double	timestamp_ = 0,
		SimdYuvType	yuvType_ = SimdYuvUnknown
	)

Creates a new Frame structure with specified width, height and pixel format.

Allocates owned planes. See the width/height constructor for Nv12 / Yuv420p even-size and yuvType rules.

Parameters

[in]	size	- a size (width and height) of created frame.
[in]	format_	- a pixel format of created frame.
[in]	flipped_	- a flag of a vertically flipped image of the created frame. It is equal to false by default.
[in]	timestamp_	- a timestamp of the created frame. It is equal to 0 by default.
[in]	yuvType_	- a YUV format type of the created frame. It is equal to SimdYuvUnknown by default.

Frame() [8/8]

SIMD_INLINE Frame	(	size_t	width_,
		size_t	height_,
		Format	format_,
		uint8_t *	data0,
		size_t	stride0,
		uint8_t *	data1,
		size_t	stride1,
		uint8_t *	data2,
		size_t	stride2,
		bool	flipped_ = false,
		double	timestamp_ = 0,
		SimdYuvType	yuvType_ = SimdYuvUnknown,
		DeleterPtr	deleter = NULL,
		void *	context = NULL
	)

Creates a new Frame structure with specified width, height and pixel format around external buffers.

The frame does not own the buffers. Unused plane pointers (data1, data2) are ignored for packed formats. Nv12 uses data0/data1, Yuv420p and Yuv444p use data0/data1/data2. If deleter is not NULL it is called from the destructor with context.

Parameters

[in]	width_	- a width of created frame.
[in]	height_	- a height of created frame.
[in]	format_	- a pixel format of created frame.
[in]	data0	- a pointer to the pixel data of first image plane.
[in]	stride0	- a row size of first image plane.
[in]	data1	- a pointer to the pixel data of second image plane.
[in]	stride1	- a row size of second image plane.
[in]	data2	- a pointer to the pixel data of third image plane.
[in]	stride2	- a row size of third image plane.
[in]	flipped_	- a flag of a vertically flipped image of the created frame. It is equal to false by default.
[in]	timestamp_	- a timestamp of the created frame. It is equal to 0 by default.
[in]	yuvType_	- a YUV format type of the created frame. It is equal to SimdYuvUnknown by default.
[in]	deleter	- an optional callback to delete the external buffer after using. It is equal to NULL by default.
[in]	context	- a context of the callback to delete the external buffer after using. It is equal to NULL by default.

~Frame()

SIMD_INLINE ~Frame

A Frame destructor.

Calls deleter(context) when an external-buffer deleter was set.

Member Function Documentation

Clone() [1/3]

SIMD_INLINE Frame< A > * Clone

Gets a copy of current frame.

Allocates a new Frame on the heap and copies pixel data of all used planes. Prefer Copy() when a stack object is enough.

Returns

a pointer to the new Frame structure. The user must free this pointer after usage.

Clone() [2/3]

SIMD_INLINE Frame< A > * Clone

(

const Rectangle< ptrdiff_t > &

rect

)

const

Gets a copy of region of current frame which is bounded by the rectangle with specified coordinates.

The region is taken with Region(rect) and then cloned. For Nv12 and Yuv420p the rectangle is aligned to even coordinates.

Parameters

[in]

rect

- a rectangle which bounds the region.

Returns

- a pointer to the new Frame structure. The user must free this pointer after usage.

Clone() [3/3]

Frame * Clone

(

Frame< A > &

buffer

)

const

Gets a copy of current frame using buffer as a storage.

Grows buffer planes when they are smaller than the current planes. The returned Frame is not owner of pixel data.

Parameters

[in,out]

buffer

- an external frame as a buffer.

Returns

a pointer to the new Frame structure (not owner). The user must free this pointer after usage.

Copy() [1/2]

Frame Copy

(

)

const

Gets a copy of current frame by value.

The copy has the same width, height, format, flipped, timestamp and yuvType. Pixel data of all used planes are copied.

Returns

a new Frame structure containing a copy of the frame.

Copy() [2/2]

Frame Copy

(

const Rectangle< ptrdiff_t > &

rect

)

const

Gets a copy of region of current frame bounded by the rectangle with specified coordinates, by value.

The region is taken with Region(rect) and then copied. For Nv12 and Yuv420p the rectangle is aligned to even coordinates.

Parameters

[in]

rect

- a rectangle which bounds the region.

Returns

a new Frame structure containing a copy of the region.

operator=() [1/2]

Frame & operator=

(

const Frame< A > &

frame

)

Creates reference to other Frame structure.

Note

This function does not create a copy of the frame! It only creates a reference to the same planes.

Parameters

[in]

frame

- an original frame.

Returns

a reference to itself.

operator=() [2/2]

Frame & operator=

(

Frame< A > &&

frame

)

Moves Frame structure.

Clears this frame and then swaps it with frame.

Parameters

[in]

frame

- a moved frame.

Returns

a reference to itself.

Ref()

SIMD_INLINE Frame< A > & Ref

Creates reference to itself.

It is used to pass a temporary Frame as a non-const argument, for example:

Simd::Convert(input, Frame(grayView).Ref());

Returns

a reference to itself.

Recreate() [1/2]

SIMD_INLINE void Recreate	(	size_t	width_,
		size_t	height_,
		Format	format_,
		SimdYuvType	yuvType_ = SimdYuvUnknown
	)

Re-creates a Frame structure with specified width, height and pixel format.

Allocates owned planes for format_. Nv12 and Yuv420p require even width and height. For YUV formats yuvType_ equal to SimdYuvUnknown is replaced by SimdYuvBt601. Packed formats set yuvType to SimdYuvUnknown. flipped and timestamp are not changed.

Parameters

[in]	width_	- a width of re-created frame.
[in]	height_	- a height of re-created frame.
[in]	format_	- a pixel format of re-created frame.
[in]	yuvType_	- a YUV format type of re-created frame. It is equal to SimdYuvUnknown by default.

Recreate() [2/2]

SIMD_INLINE void Recreate	(	const Point< ptrdiff_t > &	size,
		Format	format_,
		SimdYuvType	yuvType_ = SimdYuvUnknown
	)

Re-creates a Frame structure with specified width, height and pixel format.

See Recreate(width, height, format, yuvType) for Nv12 / Yuv420p even-size and yuvType rules.

Parameters

[in]	size	- a size (width and height) of re-created frame.
[in]	format_	- a pixel format of re-created frame.
[in]	yuvType_	- a YUV format type of re-created frame. It is equal to SimdYuvUnknown by default.

Region() [1/6]

SIMD_INLINE Frame< A > Region	(	const ptrdiff_t &	left,
		const ptrdiff_t &	top,
		const ptrdiff_t &	right,
		const ptrdiff_t &	bottom
	)		const

Creates a new Frame structure which points to the region of current frame bounded by the rectangle with specified coordinates.

The result is a reference to the same pixel data, not a copy. For Nv12 and Yuv420p the rectangle is aligned to even coordinates and chroma planes are taken at half size.

Parameters

[in]	left	- a left side of the region.
[in]	top	- a top side of the region.
[in]	right	- a right side of the region.
[in]	bottom	- a bottom side of the region.

Returns

- a new Frame structure which points to the region of frame.

Region() [2/6]

SIMD_INLINE Frame< A > Region	(	ptrdiff_t &	left,
		ptrdiff_t &	top,
		ptrdiff_t &	right,
		ptrdiff_t &	bottom
	)		const

Creates a new Frame structure which points to the region of current frame bounded by the rectangle with specified coordinates.

The arguments are clamped to the frame and, for Nv12 and Yuv420p, aligned to even coordinates. The actual region is written back.

Parameters

[in,out]	left	- a left side of the required region. Returns the left side of the actual region.
[in,out]	top	- a top side of the required region. Returns the top side of the actual region.
[in,out]	right	- a right side of the required region. Returns the right side of the actual region.
[in,out]	bottom	- a bottom side of the required region. Returns the bottom side of the actual region.

Returns

- a new Frame structure which points to the region of frame.

Region() [3/6]

SIMD_INLINE Frame< A > Region	(	const Point< ptrdiff_t > &	topLeft,
		const Point< ptrdiff_t > &	bottomRight
	)		const

Creates a new Frame structure which points to the region of frame bounded by the rectangle with specified coordinates.

The result is a reference to the same pixel data, not a copy.

Parameters

[in]	topLeft	- a top-left corner of the region.
[in]	bottomRight	- a bottom-right corner of the region.

Returns

- a new Frame structure which points to the region of frame.

Region() [4/6]

SIMD_INLINE Frame< A > Region	(	Point< ptrdiff_t > &	topLeft,
		Point< ptrdiff_t > &	bottomRight
	)		const

Creates a new Frame structure which points to the region of frame bounded by the rectangle with specified coordinates.

The arguments are clamped (and even-aligned for Nv12 and Yuv420p). The actual corners are written back.

Parameters

[in,out]	topLeft	- a top-left corner of the required region. Returns the top-left corner of the actual region.
[in,out]	bottomRight	- a bottom-right corner of the required region. Returns the bottom-right corner of the actual region.

Returns

- a new Frame structure which points to the region of frame.

Region() [5/6]

SIMD_INLINE Frame< A > Region

(

const Rectangle< ptrdiff_t > &

rect

)

const

Creates a new Frame structure which points to the region of frame bounded by the rectangle with specified coordinates.

The result is a reference to the same pixel data, not a copy.

Parameters

[in]

rect

- a rectangle which bounds the region.

Returns

- a new Frame structure which points to the region of frame.

Region() [6/6]

SIMD_INLINE Frame< A > Region

(

Rectangle< ptrdiff_t > &

rect

)

const

Creates a new Frame structure which points to the region of frame bounded by the rectangle with specified coordinates.

The rectangle is clamped (and even-aligned for Nv12 and Yuv420p). The actual region is written back to rect.

Parameters

[in,out]

rect

- a rectangle which bounds the required region. Returns the actual region.

Returns

- a new Frame structure which points to the region of frame.

Flipped()

SIMD_INLINE Frame< A > Flipped

Creates a new Frame structure which points to the vertically flipped frame.

Each used plane is flipped. The flipped flag is toggled. Compatible() and Convert() require the same flipped value on both frames.

Returns

- a new Frame structure which points to the flipped frame.

Size()

SIMD_INLINE Point< ptrdiff_t > Size

Gets size (width and height) of the frame.

Typical usage passes the result to another Frame constructor or to Simd::Resize.

Returns

- a new Point structure with frame width and height.

DataSize()

SIMD_INLINE size_t DataSize

Gets size in bytes required to store pixel data of current Frame structure.

The value is the sum of DataSize() of all planes (including unused ones).

Returns

- a size of data pixels in bytes.

Area()

SIMD_INLINE size_t Area

Gets area in pixels of current Frame structure.

The value is width * height (luma / full-frame area).

Returns

- an area of current Frame in pixels.

PlaneCount() [1/2]

SIMD_INLINE size_t PlaneCount ( Format  format )

static

Gets number of planes in the frame for the given pixel format.

None uses 0 planes, packed formats use 1, Nv12 uses 2, Yuv420p and Yuv444p use 3.

Parameters

[in]

format

- a pixel format.

Returns

- a number of planes.

PlaneCount() [2/2]

SIMD_INLINE size_t PlaneCount

Gets number of planes for current frame.

The value is PlaneCount(format). Used planes are planes[0] .. planes[PlaneCount() - 1].

Returns

- a number of planes.

Clear()

SIMD_INLINE void Clear

Clears Frame structure (resets all public fields).

Used planes are cleared. Width and height become 0, format becomes None, flipped becomes false, timestamp becomes 0, yuvType becomes SimdYuvUnknown.

Swap()

SIMD_INLINE void Swap

(

Frame< A > &

other

)

Swaps content of two (this and other) Frame structures.

All public fields and the optional deleter are exchanged.

Parameters

[in]

other

- an other frame.

Owner()

SIMD_INLINE bool Owner

Gets owner flag: do all used planes own their images?

An empty frame (PlaneCount() == 0) is not an owner.

Returns

- an owner flag.

Capture()

SIMD_INLINE void Capture

Captures image planes (copies to internal buffers) if this Frame is not owner of current image planes.

Calls View::Capture for each used plane. After the call Owner() is true when the frame is not empty.

Field Documentation

PLANE_COUNT_MAX

const size_t PLANE_COUNT_MAX = 4

static

Maximal count of pixel planes in a frame. Packed formats use 1, Nv12 uses 2, Yuv420p and Yuv444p use 3.