This class implements Ocean's image class. More...

Inheritance diagram for Ocean::Frame:

Data Structures
class	Plane
	Definition of an image plane, a block of memory storing pixel data with interleaved channels (or just one channel). More...

class	PlaneInitializer
	This class implements a helper class which can be used to initialize a multi-plane frame in the constructor. More...

Public Types
enum	CopyMode : uint32_t { CM_USE_KEEP_LAYOUT = 1u << 0u , CM_COPY_REMOVE_PADDING_LAYOUT = 1u << 1u , CM_COPY_KEEP_LAYOUT_DO_NOT_COPY_PADDING_DATA = 1u << 2u , CM_COPY_KEEP_LAYOUT_COPY_PADDING_DATA = 1u << 3u }
	Definition of individual copy modes. More...

enum	AdvancedCopyMode : std::underlying_type< CopyMode >::type { ACM_USE_KEEP_LAYOUT = CM_USE_KEEP_LAYOUT , ACM_COPY_REMOVE_PADDING_LAYOUT = CM_COPY_REMOVE_PADDING_LAYOUT , ACM_COPY_KEEP_LAYOUT_DO_NOT_COPY_PADDING_DATA = CM_COPY_KEEP_LAYOUT_DO_NOT_COPY_PADDING_DATA , ACM_COPY_KEEP_LAYOUT_COPY_PADDING_DATA = CM_COPY_KEEP_LAYOUT_COPY_PADDING_DATA , ACM_USE_OR_COPY = ACM_USE_KEEP_LAYOUT \| ACM_COPY_REMOVE_PADDING_LAYOUT , ACM_USE_OR_COPY_KEEP_LAYOUT = ACM_USE_KEEP_LAYOUT \| ACM_COPY_KEEP_LAYOUT_DO_NOT_COPY_PADDING_DATA }
	Definition of advanced copy modes containing all copy modes from `CopyMode` but also some additional. More...

using	Planes = StackHeapVector< Plane, 4 >
	Definition of a vector storing planes. More...

template<typename T >
using	PlaneInitializers = std::vector< PlaneInitializer< T > >
	Definition of a vector holding plane initializer objects. More...

template<typename T , unsigned int tChannels>
using	PixelType = typename Ocean::DataType< T, tChannels >::Type
	Definition of a data type storing all channel values of one pixel in an array. More...

Public Types inherited from Ocean::FrameType
enum	DataType : uint8_t { DT_UNDEFINED = 0u , DT_UNSIGNED_INTEGER_8 , DT_SIGNED_INTEGER_8 , DT_UNSIGNED_INTEGER_16 , DT_SIGNED_INTEGER_16 , DT_UNSIGNED_INTEGER_32 , DT_SIGNED_INTEGER_32 , DT_UNSIGNED_INTEGER_64 , DT_SIGNED_INTEGER_64 , DT_SIGNED_FLOAT_16 , DT_SIGNED_FLOAT_32 , DT_SIGNED_FLOAT_64 , DT_END }
	Definition of individual channel data type. More...

enum	PixelFormat : uint64_t { FORMAT_UNDEFINED = 0ull , FORMAT_ABGR32 = 1ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_4, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_ARGB32 = 2ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_4, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_BGR24 = 3ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_3, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_BGR32 = 4ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_4, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_BGR4444 = 5ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_16, CV_CHANNELS_UNDEFINED , PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_BGR5551 = 6ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_16, CV_CHANNELS_UNDEFINED , PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_BGR565 = 7ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_16, CV_CHANNELS_UNDEFINED , PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_BGRA32 = 8ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_4, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_BGRA4444 = 9ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_16, CV_CHANNELS_UNDEFINED , PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_BGGR10_PACKED = 10ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_1, MV_MULTIPLE_4, MV_MULTIPLE_2>::value , FORMAT_RGB24 = 11ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_3, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_RGB32 = 12ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_4, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_RGB4444 = 13ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_16, CV_CHANNELS_UNDEFINED , PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_RGB5551 = 14ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_16, CV_CHANNELS_UNDEFINED , PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_RGB565 = 15ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_16, CV_CHANNELS_UNDEFINED , PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_RGBA32 = 16ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_4, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_RGBA4444 = 17ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_16, CV_CHANNELS_UNDEFINED , PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_RGBT32 = 18ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_4, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_RGGB10_PACKED = 19ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_1, MV_MULTIPLE_4, MV_MULTIPLE_2>::value , FORMAT_Y_U_V12 = 20ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_3, MV_MULTIPLE_2, MV_MULTIPLE_2>::value , FORMAT_YUV24 = 21ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_3, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_YUVA32 = 22ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_4, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_YUVT32 = 23ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_4, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_Y_V_U12 = 24ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_3, MV_MULTIPLE_2, MV_MULTIPLE_2>::value , FORMAT_YVU24 = 25ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_3, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_Y_UV12 = 26ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_2, MV_MULTIPLE_2, MV_MULTIPLE_2>::value , FORMAT_Y_VU12 = 27ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_2, MV_MULTIPLE_2, MV_MULTIPLE_2>::value , FORMAT_YUYV16 = 28ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_1, MV_MULTIPLE_2, MV_MULTIPLE_1>::value , FORMAT_UYVY16 = 29ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_1, MV_MULTIPLE_2, MV_MULTIPLE_1>::value , FORMAT_Y8 = 30ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_1, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_Y10 = 31ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_16, CV_CHANNELS_1, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_Y10_PACKED = 32ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_1, MV_MULTIPLE_4, MV_MULTIPLE_1>::value , FORMAT_Y16 = 33ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_16, CV_CHANNELS_1, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_Y32 = 34ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_32, CV_CHANNELS_1, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_Y64 = 35ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_64, CV_CHANNELS_1, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_YA16 = 36ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_2, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_RGB48 = 37ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_16, CV_CHANNELS_3, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_RGBA64 = 38ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_16, CV_CHANNELS_4, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_Y_U_V24 = 39ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_3, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_Y_U_V24_LIMITED_RANGE = FORMAT_Y_U_V24 , FORMAT_Y_U_V24_FULL_RANGE = 40ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_3, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_Y8_LIMITED_RANGE = 41ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_1, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_Y8_FULL_RANGE = FORMAT_Y8 , FORMAT_Y_UV12_LIMITED_RANGE = FORMAT_Y_UV12 , FORMAT_Y_UV12_FULL_RANGE = 42ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_2, MV_MULTIPLE_2, MV_MULTIPLE_2>::value , FORMAT_Y_VU12_LIMITED_RANGE = FORMAT_Y_VU12 , FORMAT_Y_VU12_FULL_RANGE = 43ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_2, MV_MULTIPLE_2, MV_MULTIPLE_2>::value , FORMAT_Y_U_V12_LIMITED_RANGE = FORMAT_Y_U_V12 , FORMAT_Y_U_V12_FULL_RANGE = 44ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_3, MV_MULTIPLE_2, MV_MULTIPLE_2>::value , FORMAT_Y_V_U12_LIMITED_RANGE = FORMAT_Y_V_U12 , FORMAT_Y_V_U12_FULL_RANGE = 45ull \| GenericPixelFormat<DT_UNSIGNED_INTEGER_8, CV_CHANNELS_UNDEFINED , PV_PLANES_3, MV_MULTIPLE_2, MV_MULTIPLE_2>::value , FORMAT_F32 = 46ull \| GenericPixelFormat<DT_SIGNED_FLOAT_32, CV_CHANNELS_1, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_F64 = 47ull \| GenericPixelFormat<DT_SIGNED_FLOAT_64, CV_CHANNELS_1, PV_PLANES_1, MV_MULTIPLE_1, MV_MULTIPLE_1>::value , FORMAT_END = 48ull }
	Definition of all pixel formats available in the Ocean framework. More...

enum	PixelOrigin : uint32_t { ORIGIN_INVALID = 0u , ORIGIN_UPPER_LEFT , ORIGIN_LOWER_LEFT }
	Defines different types of frame origin positions. More...

using	DataTypes = std::vector< DataType >
	Definition of a vector holding data types. More...

using	PixelFormats = std::vector< PixelFormat >
	Definition of a vector holding pixel formats. More...

Public Member Functions
	Frame ()
	Creates an empty frame. More...

	Frame (const Frame &frame)
	Creates a second version of a given frame. More...

	Frame (Frame &&frame) noexcept
	Move constructor. More...

	Frame (const Frame &frame, const AdvancedCopyMode advancedCopyMode) noexcept
	Creates a second version of a given frame. More...

	Frame (const FrameType &frameType, const Indices32 &paddingElementsPerPlane=Indices32(), const Timestamp &timestamp=Timestamp(false))
	Creates a frame with specified width, height, pixel format and frame origin and an optional padding. More...

	Frame (const FrameType &frameType, const unsigned int paddingElements, const Timestamp &timestamp=Timestamp(false))
	Deprecated: Use Frame(const FrameType& frameType, const Indices32& paddingElements, const Timestamp& timestamp) instead. More...

template<typename T >
	Frame (const FrameType &frameType, const T *data, const CopyMode copyMode, const unsigned int paddingElements=0u, const Timestamp &timestamp=Timestamp(false))
	Creates a new one-plane frame with known frame type with read-only source memory. More...

template<typename T >
	Frame (const FrameType &frameType, T *data, const CopyMode copyMode, const unsigned int paddingElements=0u, const Timestamp &timestamp=Timestamp(false))
	Creates a new one-plane frame with known frame type with writable source memory. More...

template<typename T >
	Frame (const FrameType &frameType, const PlaneInitializers< T > &planeInitializers, const Timestamp &timestamp=Timestamp(false))
	Creates a new multi-plane frame with known frame type and given source memory for each individual plane. More...

	~Frame ()
	Destructs a frame. More...

const FrameType &	frameType () const
	Returns the frame type of this frame. More...

const Planes &	planes () const
	Returns the individual planes of this frame. More...

bool	copy (const Frame &source, const bool copyTimestamp=true)
	Deprecated. More...

bool	copy (const int targetLeft, const int targetTop, const Frame &source, const bool copyTimestamp=true)
	Copies the entire image content of a source frame into this frame. More...

bool	set (const FrameType &frameType, const bool forceOwner, const bool forceWritable=false, const Indices32 &planePaddingElements=Indices32(), const Timestamp &timestamp=Timestamp(false), bool *reallocated=nullptr)
	Sets a new frame type for this frame. More...

template<typename T >
bool	updateMemory (const T *data, const unsigned int planeIndex=0u)
	Updates the memory pointer for a specific plane of the frame to a new read-only memory location. More...

template<typename T >
bool	updateMemory (T *data, const unsigned int planeIndex=0u)
	Updates the memory pointer for a specific plane of the frame to a new read-only or writable memory location. More...

template<typename T >
bool	updateMemory (const std::initializer_list< T * > &planeDatas)
	Updates the memory pointers for all or some of the planes of the frame to new writable memory locations. More...

void	makeContinuous ()
	Makes the memory of this frame continuous. More...

void	makeOwner ()
	Makes this frame the owner of the memory. More...

Frame	subFrame (const unsigned int subFrameLeft, const unsigned int subFrameTop, const unsigned int subFrameWidth, const unsigned int subFrameHeight, const CopyMode copyMode=CM_USE_KEEP_LAYOUT) const
	Returns a sub-frame of this frame. More...

bool	setValue (const uint8_t value, const unsigned int planeIndex=0u, const bool skipPaddingData=true)
	Sets the memory of the frame to a specified byte value (the memory of one plane). More...

template<typename T , const unsigned int tPlaneChannels>
bool	setValue (const PixelType< T, tPlaneChannels > &planePixelValue, const unsigned int planeIndex=0u)
	Sets the memory of the frame to a specified pixel value (the memory of one plane). More...

template<typename T >
bool	setValue (const T *planePixelValue, const size_t planePixelValueSize, const unsigned int planeIndex=0u)
	Sets the memory of the frame to a specified pixel value (the memory of one plane). More...

template<typename T >
bool	setValue (const std::initializer_list< typename Identity< T >::Type > &planePixelValues, const unsigned int planeIndex=0u)
	Sets the memory of the frame to a specified pixel value (the memory of one plane). More...

template<typename T , const unsigned int tPlaneChannels>
bool	containsValue (const PixelType< T, tPlaneChannels > &planePixelValue, const unsigned int planeIndex=0u) const
	Returns whether the frame (one plane) contains a specified pixel value. More...

unsigned int	size (const unsigned int planeIndex=0u) const
	Returns the number of bytes necessary for a specific plane including optional padding at the end of plane rows. More...

unsigned int	paddingElements (const unsigned int planeIndex=0u) const
	Returns the optional number of padding elements at the end of each row for a specific plane. More...

unsigned int	paddingBytes (const unsigned int planeIndex=0u) const
	Returns the optional number of padding bytes at the end of each row for a specific plane. More...

unsigned int	strideElements (const unsigned int planeIndex=0u) const
	Returns the number of elements within one row, including optional padding at the end of a row for a specific plane. More...

unsigned int	strideBytes (const unsigned int planeIndex=0u) const
	Returns the number of bytes within one row, including optional padding at the end of a row for a specific plane. More...

unsigned int	planeWidth (const unsigned int planeIndex) const
	Returns the width of a plane of this frame. More...

unsigned int	planeHeight (const unsigned int planeIndex) const
	Returns the height of a plane of this frame. More...

unsigned int	planeChannels (const unsigned int planeIndex) const
	Returns the channels of a plane of this frame. More...

unsigned int	planeWidthElements (const unsigned int planeIndex) const
	Returns the width of a plane of this frame, not in pixel, but in elements, not including padding at the end of each plane row. More...

unsigned int	planeWidthBytes (const unsigned int planeIndex) const
	Returns the width of a plane of this frame, not in pixel, but in bytes, not including padding at the end of each plane row. More...

unsigned int	planeBytesPerPixel (const unsigned int planeIndex) const
	Returns the number of bytes of one pixel of a plane for a pixel format. More...

bool	isPlaneContinuous (const unsigned int planeIndex=0u) const
	Returns whether a specific plane of this frame is based on continuous memory and thus does not have any padding at the end of rows. More...

bool	isPlaneOwner (const unsigned int planeIndex=0u) const
	Returns whether a specific plane of this frame is the owner of the memory. More...

const Timestamp &	timestamp () const
	Returns the timestamp of this frame. More...

const Timestamp &	relativeTimestamp () const
	Returns the relative timestamp of this frame. More...

void	setTimestamp (const Timestamp &timestamp)
	Sets the timestamp of this frame. More...

void	setRelativeTimestamp (const Timestamp &relative)
	Sets the relative timestamp of this frame. More...

void	release ()
	Releases this frame and the frame data if this frame is the owner. More...

template<typename T >
T *	data (const unsigned int planeIndex=0u)
	Returns a pointer to the pixel data of a specific plane. More...

template<typename T >
const T *	constdata (const unsigned int planeIndex=0u) const
	Returns a pointer to the read-only pixel data of a specific plane. More...

template<typename T >
T *	row (const unsigned int y, const unsigned int planeIndex=0u)
	Returns the pointer to the pixel data of a specific row. More...

template<typename T >
const T *	constrow (const unsigned int y, const unsigned int planeIndex=0u) const
	Returns the pointer to the constant data of a specific row. More...

template<typename T >
T *	pixel (const unsigned int x, const unsigned int y, const unsigned int planeIndex=0u)
	Returns the pointer to the data of a specific pixel. More...

template<typename T >
const T *	constpixel (const unsigned int x, const unsigned int y, const unsigned int planeIndex=0u) const
	Returns the pointer to the constant data of a specific pixel. More...

bool	isContinuous () const
	Returns whether all planes of this frame have continuous memory and thus do not contain any padding at the end of their rows. More...

bool	isOwner () const
	Returns whether the frame is the owner of the internal frame data. More...

bool	isReadOnly () const
	Returns true, if the frame allows only read access (using constdata()). More...

bool	hasAlphaChannel () const
	Returns whether the frame's pixel format contains an alpha channel. More...

template<typename T >
bool	hasTransparentPixel (const T opaque) const
	Returns whether the frame holds at least one pixel with an non opaque alpha value. More...

bool	isValid () const
	Returns whether this frame is valid. More...

bool	haveIntersectingMemory (const Frame &frame) const
	Returns whether two frame objects have any amount of intersecting memory. More...

	operator bool () const
	Returns whether this frame object is valid and holds a frame. More...

Frame &	operator= (const Frame &right) noexcept
	Assign operator. More...

Frame &	operator= (Frame &&right) noexcept
	Move operator. More...

template<>
	Frame (const FrameType &frameType, const void *data, const CopyMode copyMode, const unsigned int paddingElements, const Timestamp &timestamp)

template<>
	Frame (const FrameType &frameType, void *data, const CopyMode copyMode, const unsigned int paddingElements, const Timestamp &timestamp)

template<>
bool	hasTransparentPixel (const uint8_t opaque) const

template<>
bool	hasTransparentPixel (const uint16_t opaque) const

Public Member Functions inherited from Ocean::FrameType
	FrameType ()=default
	Creates a new frame type with invalid parameters. More...

	FrameType (const unsigned int width, const unsigned int height, const PixelFormat pixelFormat, const PixelOrigin pixelOrigin)
	Creates a new frame type. More...

	FrameType (const FrameType &type, const unsigned int width, const unsigned int height)
	Creates a new frame type. More...

	FrameType (const FrameType &type, const PixelFormat pixelFormat)
	Creates a new frame type. More...

	FrameType (const FrameType &type, const PixelOrigin pixelOrigin)
	Creates a new frame type. More...

	FrameType (const FrameType &type, const PixelFormat pixelFormat, const PixelOrigin pixelOrigin)
	Creates a new frame type. More...

unsigned int	width () const
	Returns the width of the frame format in pixel. More...

unsigned int	height () const
	Returns the height of the frame in pixel. More...

PixelFormat	pixelFormat () const
	Returns the pixel format of the frame. More...

void	setPixelFormat (const PixelFormat pixelFormat)
	Explicitly changes the pixel format of this frame. More...

DataType	dataType () const
	Returns the data type of the pixel format of this frame. More...

unsigned int	bytesPerDataType () const
	Returns the number of bytes which are necessary to store the data type of this frame. More...

unsigned int	channels () const
	Returns the number of individual channels the frame has. More...

uint32_t	numberPlanes () const
	Returns the number of planes of the pixel format of this frame. More...

PixelOrigin	pixelOrigin () const
	Returns the pixel origin of the frame. More...

unsigned int	pixels () const
	Returns the number of pixels for the frame. More...

unsigned int	frameTypeSize () const
	Returns the number of bytes necessary for the frame type, without padding at the end of frame rows. More...

bool	isPixelFormatCompatible (const PixelFormat pixelFormat) const
	Returns whether the pixel format of this frame type is compatible with a given pixel format. More...

bool	isFrameTypeCompatible (const FrameType &frameType, const bool allowDifferentPixelOrigins) const
	Returns whether this frame type is compatible with a given frame type. More...

bool	operator== (const FrameType &right) const
	Returns whether two frame types are equal. More...

bool	operator!= (const FrameType &right) const
	Returns whether two frame types are not equal. More...

bool	operator< (const FrameType &right) const
	Returns whether the left frame type is 'smaller' than the right one. More...

bool	isValid () const
	Returns whether this frame type is valid. More...

template<FrameType::DataType tDataType, uint32_t tChannels, uint32_t tPlanes, uint32_t tWidthMultiple, uint32_t tHeightMultiple>
constexpr FrameType::PixelFormat	genericPixelFormat ()

template<FrameType::DataType tDataType>
constexpr FrameType::PixelFormat	genericPixelFormat (const uint32_t channels, const uint32_t planes, const uint32_t widthMultiple, const uint32_t heightMultiple)

Static Public Member Functions
static bool	strideBytes2paddingElements (const PixelFormat &pixelFormat, const unsigned int imageWidth, const unsigned int planeStrideBytes, unsigned int &planePaddingElements, const unsigned int planeIndex=0u)
	Determines the number of padding elements at the end of a row of a plane for which the pixel format, the image width and the plane's stride (in bytes) are known. More...

Static Public Member Functions inherited from Ocean::FrameType
static unsigned int	channels (const PixelFormat pixelFormat)
	Returns the number of individual channels of a given pixel format. More...

static uint32_t	numberPlanes (const PixelFormat pixelFormat)
	Returns the number of planes of a pixel format. More...

template<typename T >
static constexpr DataType	dataType ()
	Returns the (pixel format) data type of a given C++ data type. More...

static DataType	dataType (const PixelFormat pixelFormat)
	Returns the data type of a pixel format. More...

static unsigned int	bytesPerDataType (const DataType dataType)
	Returns the number of bytes which are necessary to store a specified data type. More...

static constexpr PixelFormat	genericPixelFormat (const DataType dataType, const uint32_t channels, const uint32_t planes=1u, const uint32_t widthMultiple=1u, const uint32_t heightMultiple=1u)
	Returns a specific generic pixel format with a specified data type, channel number, and plane number. More...

static PixelFormat	genericPixelFormat (const unsigned int bitsPerPixelChannel, const uint32_t channels, const uint32_t planes=1u, const uint32_t widthMultiple=1u, const uint32_t heightMultiple=1u)
	Returns a specific generic pixel format with specified bit per pixel per channel, channel number, and plane number. More...

template<DataType tDataType, uint32_t tChannels, uint32_t tPlanes = 1u, uint32_t tWidthMultiple = 1u, uint32_t tHeightMultiple = 1u>
constexpr static PixelFormat	genericPixelFormat ()
	Returns a specific generic pixel format with a specified data type and channel number. More...

template<DataType tDataType>
constexpr static PixelFormat	genericPixelFormat (const uint32_t channels, const uint32_t planes=1u, const uint32_t widthMultiple=1u, const uint32_t heightMultiple=1u)
	Returns a specific generic pixel format with a specified data type and channel number. More...

template<typename TDataType , uint32_t tChannels, uint32_t tPlanes = 1u, uint32_t tWidthMultiple = 1u, uint32_t tHeightMultiple = 1u>
constexpr static PixelFormat	genericPixelFormat ()
	Returns a specific generic pixel format with a specified data type and channel number. More...

template<typename TDataType >
constexpr static PixelFormat	genericPixelFormat (uint32_t channels, const uint32_t planes=1u, const uint32_t widthMultiple=1u, const uint32_t heightMultiple=1u)
	Returns a specific generic pixel format with a specified data type and channel number. More...

static PixelFormat	makeGenericPixelFormat (const PixelFormat pixelFormat)
	Converts a any pixel format into a generic one This function has no effect for input pixel formats which are already generic. More...

static bool	formatIsGeneric (const PixelFormat pixelFormat, const DataType dataType, const uint32_t channels, const uint32_t planes=1u, const uint32_t widthMultiple=1u, const uint32_t heightMultiple=1u)
	Checks whether a given pixel format is a specific layout regarding data channels and data type. More...

static bool	formatIsGeneric (const PixelFormat pixelFormat)
	Checks whether a given pixel format is a generic pixel format. More...

static bool	formatIsPureGeneric (const PixelFormat pixelFormat)
	Checks whether a given pixel format is a pure generic pixel format. More...

static unsigned int	formatGenericNumberChannels (const PixelFormat pixelFormat)
	Returns the number of individual channels of a given generic pixel format. More...

static unsigned int	formatGenericBitsPerPixel (const PixelFormat pixelFormat)
	Returns the number of bits of one pixel for a given generic pixel format. More...

static unsigned int	formatBitsPerPixelRedChannel (const PixelFormat pixelFormat)
	Returns the number of bits of one pixel for the red channel. More...

static unsigned int	formatBitsPerPixelGreenChannel (const PixelFormat pixelFormat)
	Returns the number of bits of one pixel for the green channel. More...

static unsigned int	formatBitsPerPixelBlueChannel (const PixelFormat pixelFormat)
	Returns the number of bits of one pixel for the blue channel. More...

static unsigned int	formatBitsPerPixelAlphaChannel (const PixelFormat pixelFormat)
	Returns the number of bits of one pixel for the alpha channel. More...

static bool	formatHasAlphaChannel (const PixelFormat pixelFormat, bool *isLastChannel=nullptr)
	Returns whether a given pixel format holds an alpha channel. More...

static bool	formatIsPacked (const PixelFormat pixelFormat)
	Returns whether a given pixel format is a packed pixel format. More...

static PixelFormat	genericSinglePlanePixelFormat (const PixelFormat pixelFormat)
	Returns the most suitable 1-plane pixel format for a given pixel format which may be composed of several planes. More...

static PixelFormat	formatAddAlphaChannel (const PixelFormat pixelFormat, const bool lastChannel=true)
	Adds an alpha channel to a given pixel format. More...

static PixelFormat	formatRemoveAlphaChannel (const PixelFormat pixelFormat)
	Removes an alpha channel from a given pixel format. More...

static unsigned int	widthMultiple (const PixelFormat pixelFormat)
	Returns the number of pixels the width of a frame must be a multiple of. More...

static unsigned int	heightMultiple (const PixelFormat pixelFormat)
	Returns the number of pixels the height of a frame must be a multiple of. More...

static unsigned int	planeChannels (const PixelFormat &imagePixelFormat, const unsigned int planeIndex)
	Returns the channels of a plane for a pixel format. More...

static unsigned int	planeBytesPerPixel (const PixelFormat &imagePixelFormat, const unsigned int planeIndex)
	Returns the number of bytes of one pixel of a plane for a pixel format. More...

static bool	planeLayout (const PixelFormat imagePixelFormat, const unsigned int imageWidth, const unsigned int imageHeight, const unsigned int planeIndex, unsigned int &planeWidth, unsigned int &planeHeight, unsigned int &planeChannels, unsigned int planeWidthElementsMultiple=nullptr, unsigned int planeHeightElementsMultiple=nullptr)
	Returns the plane layout of a given pixel format. More...

static bool	planeLayout (const FrameType &frameType, const unsigned int planeIndex, unsigned int &planeWidth, unsigned int &planeHeight, unsigned int &planeChannels, unsigned int planeWidthElementsMultiple=nullptr, unsigned int planeHeightElementsMultiple=nullptr)
	Returns the plane layout of a given frame type. More...

static DataType	translateDataType (const std::string &dataType)
	Translates a string containing a data type into the data type. More...

static PixelFormat	translatePixelFormat (const std::string &pixelFormat)
	Translates a string containing a pixel format into the pixel format. More...

static PixelOrigin	translatePixelOrigin (const std::string &pixelOrigin)
	Translates a string containing the pixel origin into the pixel origin value. More...

static std::string	translateDataType (const DataType dataType)
	Translates a data type value into a string containing the data type. More...

static std::string	translatePixelFormat (const PixelFormat pixelFormat)
	Translates a pixel format value into a string containing the pixel format. More...

static std::string	translatePixelOrigin (const PixelOrigin pixelOrigin)
	Translates a pixel origin value into a string containing the pixel origin. More...

static PixelFormat	findPixelFormat (const unsigned int bitsPerPixel)
	Returns a best fitting pixel format having the given number of bits per pixels. More...

static PixelFormat	findPixelFormat (const DataType dataType, const unsigned int channels)
	Returns a best fitting pixel format having the given number of bits per pixels. More...

static bool	arePixelFormatsCompatible (const PixelFormat pixelFormatA, const PixelFormat pixelFormatB)
	Returns whether two given pixel formats are compatible. More...

static bool	areFrameTypesCompatible (const FrameType &frameTypeA, const FrameType &frameTypeB, const bool allowDifferentPixelOrigins)
	Returns whether two given frame types are compatible. More...

template<typename T >
static bool	dataIsAligned (const void *data)
	Returns whether a given pointer has the same byte alignment as the size of the data type the pointer is pointing to. More...

static const FrameType::DataTypes &	definedDataTypes ()
	Returns all defined data types. More...

static const FrameType::PixelFormats &	definedPixelFormats ()
	Returns all defined pixel formats. More...

template<>
constexpr FrameType::DataType	dataType ()

template<>
constexpr FrameType::DataType	dataType ()

template<>
constexpr FrameType::DataType	dataType ()

template<>
constexpr FrameType::DataType	dataType ()

template<>
constexpr FrameType::DataType	dataType ()

template<>
constexpr FrameType::DataType	dataType ()

template<>
constexpr FrameType::DataType	dataType ()

template<>
constexpr FrameType::DataType	dataType ()

template<>
constexpr FrameType::DataType	dataType ()

template<>
constexpr FrameType::DataType	dataType ()

template<>
constexpr FrameType::DataType	dataType ()

template<>
constexpr FrameType::DataType	dataType ()

template<>
constexpr FrameType::DataType	dataType ()

Protected Member Functions
	Frame (const FrameType &frameType, const PlaneInitializer< void > *planeInitializers, size_t sizePlaneInitializers, const Timestamp &timestamp=Timestamp(false))
	Creates a new multi-plane frame with known frame type and given source memory for each individual plane. More...

	Frame (const Frame &frame, const bool copyData)=delete
	Deleted constructor to prevent misuse. More...

	Frame (const FrameType &frameType, const CopyMode copyMode)=delete
	Deleted constructor to prevent misuse. More...

	Frame (const FrameType &frameType, const AdvancedCopyMode avancedCopyMode)=delete
	Deleted constructor to prevent misuse. More...

	Frame (const Frame &frame, const CopyMode copyMode)=delete
	Deleted constructor to prevent misuse, use `AdvancedCopyMode` instead. More...

	Frame (const FrameType &frameType, const Timestamp &timestamp)=delete
	Deleted constructor to prevent misuse. More...

	Frame (const Frame &frame, const Timestamp &timestamp)=delete
	Deleted constructor to prevent misuse. More...

template<typename T >
	Frame (const FrameType &frameType, const T *data, const bool copyData, const unsigned int paddingElements=0u, const Timestamp &timestamp=Timestamp(false))=delete
	Deleted constructor to prevent misuse, use `Frame(const FrameType& frameType, const T* data, const CopyMode copyMode, const unsigned int paddingElements = 0u, const Timestamp& timestamp = Timestamp(false));` instead. More...

template<typename T >
	Frame (const FrameType &frameType, T *data, const bool copyData, const unsigned int paddingElements=0u, const Timestamp &timestamp=Timestamp(false))=delete
	Deleted constructor to prevent misuse, use `Frame(const FrameType& frameType, T* data, const CopyMode copyMode, const unsigned int paddingElements = 0u, const Timestamp& timestamp = Timestamp(false));` instead. More...

Protected Attributes
Planes	planes_
	The individual memory planes of this frame. More...

Timestamp	timestamp_
	Timestamp of the frame. More...

Timestamp	relativeTimestamp_
	Relative timestamp of this frame. More...

Additional Inherited Members
Protected Types inherited from Ocean::FrameType
enum	ChannelsValue : uint32_t { CV_CHANNELS_UNDEFINED = 0u , CV_CHANNELS_1 = 1u , CV_CHANNELS_2 = 2u , CV_CHANNELS_3 = 3u , CV_CHANNELS_4 = 4u }
	Definition of a protected helper enum that simplifies to read the definition of a predefined pixel format. More...

enum	PlanesValue : uint32_t { PV_PLANES_1 = 1u , PV_PLANES_2 = 2u , PV_PLANES_3 = 3u , PV_PLANES_4 = 4u }
	Definition of a protected helper enum that simplifies to read the definition of a predefined pixel format. More...

enum	MultipleValue : uint32_t { MV_MULTIPLE_1 = 1u , MV_MULTIPLE_2 = 2u , MV_MULTIPLE_3 = 3u , MV_MULTIPLE_4 = 4u }
	Definition of a protected helper enum that simplifies to read the definition of a predefined pixel format. More...

Static Protected Attributes inherited from Ocean::FrameType
static constexpr uint32_t	pixelFormatBitOffsetChannels = 16u
	The number of bits the channel value is shifted within the PixelFormat value. More...

static constexpr uint32_t	pixelFormatBitOffsetDatatype = pixelFormatBitOffsetChannels + 8u
	The number of bits the data type value is shifted within the PixelFormat value. More...

static constexpr uint32_t	pixelFormatBitOffsetPlanes = pixelFormatBitOffsetDatatype + 8u
	The number of bits the planes value is shifted within the PixelFormat value. More...

static constexpr uint32_t	pixelFormatBitOffsetWidthMultiple = pixelFormatBitOffsetPlanes + 8u
	The number of bits the width-multiple value is shifted within the PixelFormat value. More...

static constexpr uint32_t	pixelFormatBitOffsetHeightMultiple = pixelFormatBitOffsetWidthMultiple + 8u
	The number of bits the height-multiple value is shifted within the PixelFormat value. More...

Detailed Description

This class implements Ocean's image class.

An image is composed of several planes, each plane can store image content with interleaved color channels.

Plane 0:
 ---------------------------------- ----------------------------
|                                  |                            |
|                                  |                            |
|                                  |<--- paddingElements(0) --->|   plane height (0)
|                                  |                            |
|                                  |                            |
 ---------------------------------- ----------------------------

Plane 1:
 -------------- ------------------------
|              |                        |
|              |<- paddingElements(1) ->|   plane height (1)
|              |                        |
 -------------- ------------------------

Member Typedef Documentation

◆ PixelType

template<typename T , unsigned int tChannels>

using Ocean::Frame::PixelType = typename Ocean::DataType<T, tChannels>::Type

Definition of a data type storing all channel values of one pixel in an array.

Template Parameters

T	The data type of each pixel channel
tChannels	The number of channels the pixel has, with range [1, infinity)

◆ PlaneInitializers

template<typename T >

using Ocean::Frame::PlaneInitializers = std::vector<PlaneInitializer<T> >

Definition of a vector holding plane initializer objects.

Template Parameters

T	The data type of the frame's element type.

◆ Planes

using Ocean::Frame::Planes = StackHeapVector<Plane, 4>

Definition of a vector storing planes.

Member Enumeration Documentation

◆ AdvancedCopyMode

enum Ocean::Frame::AdvancedCopyMode : std::underlying_type< CopyMode >::type

Definition of advanced copy modes containing all copy modes from CopyMode but also some additional.

Enumerator
ACM_USE_KEEP_LAYOUT	Same as CM_USE_KEEP_LAYOUT.
ACM_COPY_REMOVE_PADDING_LAYOUT	Same as CM_COPY_REMOVE_PADDING_LAYOUT.
ACM_COPY_KEEP_LAYOUT_DO_NOT_COPY_PADDING_DATA	Same as CM_COPY_KEEP_LAYOUT_DO_NOT_COPY_PADDING_DATA.
ACM_COPY_KEEP_LAYOUT_COPY_PADDING_DATA	Same as CM_COPY_KEEP_LAYOUT_COPY_PADDING_DATA.
ACM_USE_OR_COPY	The source memory is used if the source is not owner of the memory; The source memory is copied if the source is owner of the memory, padding layout will be removed.
ACM_USE_OR_COPY_KEEP_LAYOUT	The source memory is used if the source is not owner of the memory; The source memory is copied if the source is owner of the memory, padding layout is preserved, but padding data is not copied.

◆ CopyMode

enum Ocean::Frame::CopyMode : uint32_t

Definition of individual copy modes.

Enumerator
CM_USE_KEEP_LAYOUT	The source memory is used only, no copy is created, the padding layout is preserved.
CM_COPY_REMOVE_PADDING_LAYOUT	Makes a copy of the source memory, but the new plane will not contain padding elements.
CM_COPY_KEEP_LAYOUT_DO_NOT_COPY_PADDING_DATA	Makes a copy of the source memory, the padding layout is preserved, but the padding data is not copied.
CM_COPY_KEEP_LAYOUT_COPY_PADDING_DATA	Makes a copy of the source memory, the padding layout is preserved, the padding data is copied as well.

Constructor & Destructor Documentation

◆ Frame() [1/20]

Ocean::Frame::Frame ( )

inline

Creates an empty frame.

◆ Frame() [2/20]

Ocean::Frame::Frame ( const Frame & frame )

Creates a second version of a given frame.

If the given source frame is not owner of the frame data, this new frame will also not be owner of the frame data.
But, if the given source frame is the owner of the frame data, this new frame will also be the owner of new copy of the frame data.
Thus, the following two lines of code produce the same result:

Frame newFrameA(frame);
Frame newFrameB(frame, ACM_USE_OR_COPY);
ocean_assert(newFrameB.isOwner() == false || newFrameB.isContinuous());

This function behaves similar like the normal assign operator. Whenever a copy is created, the memory layout of the resulting frame will be continuous.

Parameters

frame The frame to copy

◆ Frame() [3/20]

Ocean::Frame::Frame ( Frame && frame )

inlinenoexcept

Move constructor.

Parameters

frame The frame to be moved

◆ Frame() [4/20]

Ocean::Frame::Frame	(	const Frame &	frame,
		const AdvancedCopyMode	advancedCopyMode
	)

noexcept

Creates a second version of a given frame.

Beware: The pixel memory will either be copied or used only, this depends on 'advancedCopyMode'.

Parameters

frame	The frame to copy, can be invalid
advancedCopyMode	The copy mode to be applied

◆ Frame() [5/20]

Ocean::Frame::Frame	(	const FrameType &	frameType,
		const Indices32 &	paddingElementsPerPlane = `Indices32()`,
		const Timestamp &	timestamp = `Timestamp(false)`
	)

inlineexplicit

Creates a frame with specified width, height, pixel format and frame origin and an optional padding.

The necessary buffer is allocated but not initialized.

Parameters

frameType	Type of the frame, must be valid
paddingElementsPerPlane	The padding elements at the end of each individual plane row, in elements of the pixel format, one for each plane, an empty vector to define a frame without padding
timestamp	The timestamp of the frame

◆ Frame() [6/20]

Ocean::Frame::Frame	(	const FrameType &	frameType,
		const unsigned int	paddingElements,
		const Timestamp &	timestamp = `Timestamp(false)`
	)

inlineexplicit

Deprecated: Use Frame(const FrameType& frameType, const Indices32& paddingElements, const Timestamp& timestamp) instead.

Creates a new one-plane frame by given width, height, pixel format and frame origin and an optional padding. The necessary buffer is allocated but not initialized.

Parameters

frameType	Type of the frame, must be valid
paddingElements	Optional number of elements at the end of each row, one pixel has (1 * channels) elements, must be 0 for non-generic pixel formats (e.g., Y_UV12), with range [0, infinity)
timestamp	The timestamp of the frame

◆ Frame() [7/20]

template<typename T >

Ocean::Frame::Frame	(	const FrameType &	frameType,
		const T *	data,
		const CopyMode	copyMode,
		const unsigned int	paddingElements = `0u`,
		const Timestamp &	timestamp = `Timestamp(false)`
	)

inline

Creates a new one-plane frame with known frame type with read-only source memory.

Beware: If this frame uses the pixel data only, the provided buffer must be valid as long as this new frame exists!

Parameters

frameType	Type of the frame, must be valid
data	Frame data to copy or to use, depending on the data copy flag
copyMode	The copy mode to be applied
paddingElements	Optional number of elements at the end of each row, one pixel has (1 * channels) elements, must be 0 for non-generic pixel formats (e.g., Y_UV12), with range [0, infinity)
timestamp	The timestamp of the frame

Template Parameters

T	The data type of each pixel element, e.g., 'uint8_t', 'uint16_t', or 'float', can be `void` to force the usage of the pixel element type as defined in `frameType.pixelFormat()`

◆ Frame() [8/20]

template<typename T >

Ocean::Frame::Frame	(	const FrameType &	frameType,
		T *	data,
		const CopyMode	copyMode,
		const unsigned int	paddingElements = `0u`,
		const Timestamp &	timestamp = `Timestamp(false)`
	)

inline

Creates a new one-plane frame with known frame type with writable source memory.

Beware: If this frame uses the pixel data only, the provided buffer must be valid as long as this new frame exists!

Parameters

frameType	Type of the frame
data	Frame data to copy or to use, depending on the data copy flag
copyMode	The copy mode to be applied
paddingElements	Optional number of elements at the end of each row, one pixel has (1 * channels) elements, must be 0 for non-generic pixel formats (e.g., Y_UV12), with range [0, infinity)
timestamp	The timestamp of the frame

Template Parameters

T	The data type of each pixel element, e.g., 'uint8_t', 'uint16_t', or 'float', can be `void` to force the usage of the pixel element type as defined in `frameType.pixelFormat()`

◆ Frame() [9/20]

template<typename T >

Ocean::Frame::Frame	(	const FrameType &	frameType,
		const PlaneInitializers< T > &	planeInitializers,
		const Timestamp &	timestamp = `Timestamp(false)`
	)

inline

Creates a new multi-plane frame with known frame type and given source memory for each individual plane.

Parameters

frameType	The data type of the new frame, must be valid
planeInitializers	The initializers for the individual planes, one for each plane of the pixel format
timestamp	The timestamp of the frame

Template Parameters

T	The data type of each pixel element, e.g., 'uint8_t', 'uint16_t', or 'float', can be `void` to force the usage of the pixel element type as defined in `frameType.pixelFormat()`

◆ ~Frame()

Ocean::Frame::~Frame ( )

Destructs a frame.

◆ Frame() [10/20]

Ocean::Frame::Frame	(	const FrameType &	frameType,
		const PlaneInitializer< void > *	planeInitializers,
		size_t	sizePlaneInitializers,
		const Timestamp &	timestamp = `Timestamp(false)`
	)

protected

Creates a new multi-plane frame with known frame type and given source memory for each individual plane.

Parameters

frameType	The data type of the new frame, must be valid
planeInitializers	The initializers for the individual planes, one for each plane of the pixel format, must be valid
sizePlaneInitializers	The number of specified initializers for the individual planes, must be frameType.numberPlanes()
timestamp	The timestamp of the frame

◆ Frame() [11/20]

Ocean::Frame::Frame	(	const Frame &	frame,
		const bool	copyData
	)

protecteddelete

Deleted constructor to prevent misuse.

Parameters

frame	The frame to copy
copyData	Determines whether this new frame will make an own copy of the given frame data or whether the pixel data is used only

◆ Frame() [12/20]

Ocean::Frame::Frame	(	const FrameType &	frameType,
		const CopyMode	copyMode
	)

protecteddelete

Deleted constructor to prevent misuse.

Parameters

frameType	The frame type which would be used to create the object
copyMode	The copy mode which would be used to create the object

◆ Frame() [13/20]

Ocean::Frame::Frame	(	const FrameType &	frameType,
		const AdvancedCopyMode	avancedCopyMode
	)

protecteddelete

Deleted constructor to prevent misuse.

Parameters

frameType	The frame type which would be used to create the object
avancedCopyMode	The advanced copy mode which would be used to create the object

◆ Frame() [14/20]

Ocean::Frame::Frame	(	const Frame &	frame,
		const CopyMode	copyMode
	)

protecteddelete

Deleted constructor to prevent misuse, use AdvancedCopyMode instead.

Parameters

frame	The frame to be copied
copyMode	The copy mode which would be used to create the object

◆ Frame() [15/20]

Ocean::Frame::Frame	(	const FrameType &	frameType,
		const Timestamp &	timestamp
	)

protecteddelete

Deleted constructor to prevent misuse.

Parameters

frameType	The frame type which would be used
timestamp	The timestamp which would be used to create the object

◆ Frame() [16/20]

Ocean::Frame::Frame	(	const Frame &	frame,
		const Timestamp &	timestamp
	)

protecteddelete

Deleted constructor to prevent misuse.

Parameters

frame	The frame to be copied
timestamp	The timestamp which would be used to create the object

◆ Frame() [17/20]

template<typename T >

Ocean::Frame::Frame	(	const FrameType &	frameType,
		const T *	data,
		const bool	copyData,
		const unsigned int	paddingElements = `0u`,
		const Timestamp &	timestamp = `Timestamp(false)`
	)

protecteddelete

Deleted constructor to prevent misuse, use Frame(const FrameType& frameType, const T* data, const CopyMode copyMode, const unsigned int paddingElements = 0u, const Timestamp& timestamp = Timestamp(false)); instead.

Parameters

frameType	Type of the frame, must be valid
data	Frame data to copy or to use, depending on the data copy flag
copyData	Determines whether the frame will make an own copy of the given frame data or whether the pixel data are used only
paddingElements	Optional number of elements at the end of each row, one pixel has (1 * channels) elements, must be 0 for non-generic pixel formats (e.g., Y_UV12), with range [0, infinity)
timestamp	The timestamp of the frame

Template Parameters

T	The data type of each pixel element, e.g., 'uint8_t', 'uint16_t', or 'float', can be `void` to force the usage of the pixel element type as defined in `frameType.pixelFormat()`

◆ Frame() [18/20]

template<typename T >

Ocean::Frame::Frame	(	const FrameType &	frameType,
		T *	data,
		const bool	copyData,
		const unsigned int	paddingElements = `0u`,
		const Timestamp &	timestamp = `Timestamp(false)`
	)

protecteddelete

Deleted constructor to prevent misuse, use Frame(const FrameType& frameType, T* data, const CopyMode copyMode, const unsigned int paddingElements = 0u, const Timestamp& timestamp = Timestamp(false)); instead.

Parameters

frameType	Type of the frame
data	Frame data to copy or to use, depending on the data copy flag
copyData	Determines whether the frame will make an own copy of the given frame data or whether the pixel data are used only
paddingElements	Optional number of elements at the end of each row, one pixel has (1 * channels) elements, must be 0 for non-generic pixel formats (e.g., Y_UV12), with range [0, infinity)
timestamp	The timestamp of the frame

Template Parameters

T	The data type of each pixel element, e.g., 'uint8_t', 'uint16_t', or 'float', can be `void` to force the usage of the pixel element type as defined in `frameType.pixelFormat()`

◆ Frame() [19/20]

template<>

Ocean::Frame::Frame	(	const FrameType &	frameType,
		const void *	data,
		const CopyMode	copyMode,
		const unsigned int	paddingElements,
		const Timestamp &	timestamp
	)

inline

◆ Frame() [20/20]

template<>

Ocean::Frame::Frame	(	const FrameType &	frameType,
		void *	data,
		const CopyMode	copyMode,
		const unsigned int	paddingElements,
		const Timestamp &	timestamp
	)

inline

Member Function Documentation

◆ constdata()

template<typename T >

const T * Ocean::Frame::constdata ( const unsigned int planeIndex = 0u ) const

inline

Returns a pointer to the read-only pixel data of a specific plane.

Parameters

planeIndex The index of the plane for which the data will be returned, with range [0, planes().size())

Returns: The plane's read-only pixel data

Template Parameters

T	The explicit data type of the value of each pixel channel

See also: isValid().

◆ constpixel()

template<typename T >

const T * Ocean::Frame::constpixel	(	const unsigned int	x,
		const unsigned int	y,
		const unsigned int	planeIndex = `0u`
	)		const

inline

Returns the pointer to the constant data of a specific pixel.

Ensure that the frame is valid and that the frame holds a valid frame buffer before this function is called.

In general, the usage of this function is recommended for prototyping only.
As the location of each pixel has to be calculated every time, this function is quite slow.
Production code should use the constdata(), data(), constrow(), and row() functions instead.

The vertical location (the y coordinate) of the pixel is defined with respect to the origin of the frame's data.
Therefore, pixel<T>(0, 0) will return the top left pixel of an image if pixelOrigin() == ORIGIN_UPPER_LEFT,
and will return the bottom left pixel of an image if pixelOrigin() == ORIGIN_LOWER_LEFT.
In any case, pixel<T>(0, 0) is equivalent to data<T>().

This function most not be called for packed pixel formats.

Parameters

x	The horizontal position of the requested pixel, with range [0, planeWidth(planeIndex) - 1]
y	The vertical position of the requested pixel, with range [0, planeHeight(planeIndex) - 1]
planeIndex	The index of the plane for which the pixel will be returned, with range [0, planes().size())

Returns: The pointer to the memory at which the pixel starts

Template Parameters

T	The explicit data type of the value of each pixel channel

See also: data(), row(), pixel(), constdata(), constrow(), formatIsPacked().

◆ constrow()

template<typename T >

const T * Ocean::Frame::constrow	(	const unsigned int	y,
		const unsigned int	planeIndex = `0u`
	)		const

inline

Returns the pointer to the constant data of a specific row.

Ensure that the frame is valid and that the frame holds a valid frame buffer before this function is called.

The index of the row is defined with respect to the origin of the frame's data.
Therefore, constrow<T>(0) will return the top row of an image if pixelOrigin() == ORIGIN_UPPER_LEFT,
and will return the bottom row of an image if pixelOrigin() == ORIGIN_LOWER_LEFT.
In any case, constrow<T>(0) is equivalent to constdata<T>().

Parameters

y	The index of the row (the vertical location) to which the resulting pointer will point, with range [0, planeHeight(planeIndex) - 1]
planeIndex	The index of the plane for which the pixel will be returned, with range [0, planes().size())

Returns: The pointer to the memory at which the row starts

Template Parameters

T	The explicit data type of the value of each pixel channel

See also: data(), pixel(), constrow(), constdata(), constpixel().

◆ containsValue()

template<typename T , const unsigned int tPlaneChannels>

bool Ocean::Frame::containsValue	(	const PixelType< T, tPlaneChannels > &	planePixelValue,
		const unsigned int	planeIndex = `0u`
	)		const

Returns whether the frame (one plane) contains a specified pixel value.

Parameters

planePixelValue	The pixel value to be checked
planeIndex	The index of the plane for which the memory will be set, with range [0, numberPlanes())

Template Parameters

T	The data type of the given pixel value, must be identical to the data type of the frame
tPlaneChannels	The number of channels the plane has (not the number of channels the frame has), with range [1, channels()]

Returns: True, if at least one pixel has the specified value

◆ copy() [1/2]

bool Ocean::Frame::copy	(	const Frame &	source,
		const bool	copyTimestamp = `true`
	)

Deprecated.

Copies frame data from a source frame. When both frame types are not identical, the frame type of this frame is changed to the source frame type.
This frame will own the new frame data, thus a new frame buffer is allocated if necessary.
In case a new frame buffer needed to be allocated, the memory layout of the new frame buffer will be continuous.

Parameters

source	The source frame to copy, must be valid and must not be this frame
copyTimestamp	True, to copy the frame's timestamp; False, to copy the image data only

Returns: True, if the copy operation was successful; otherwise, the frame is not modified and false is returned.

◆ copy() [2/2]

bool Ocean::Frame::copy	(	const int	targetLeft,
		const int	targetTop,
		const Frame &	source,
		const bool	copyTimestamp = `true`
	)

Copies the entire image content of a source frame into this frame.

Both frames must have a compatible pixel format and must have the same pixel origin.
Only the intersecting image content will be copied, padding data is not copied:

                  Source frame
                   -------------------------------
This              |(targetLeft, targetTop)        |
target frame      |                               |
 -----------------|---------                      |
|(0, 0)           |XXXXXXXXX|                     |
|                 |XXXXXXXXX|                     |
|                  -------------------------------
|                           |
 ---------------------------

The intersecting image content is marked with an 'X'.

Parameters

targetLeft	The horizontal position within this image to which the top-left corner of the source image will be copied, with range (-infinity, infinity)
targetTop	The vertical position within this image to which the top-left corner of the source image will be copied, with range (-infinity, infinity)
source	The source frame to be copied, must be valid
copyTimestamp	True, to copy the frame's timestamp; False, to copy the image data only

Returns: False, if both frames are not compatible; True, if the input was valid, even if both images do not intersect

◆ data()

template<typename T >

T * Ocean::Frame::data ( const unsigned int planeIndex = 0u )

inline

Returns a pointer to the pixel data of a specific plane.

Ensure that the frame holds writable pixel data before calling this function.

Parameters

planeIndex The index of the plane for which the data will be returned, with range [0, planes().size())

Returns: The plane's writable pixel data

Template Parameters

T	The explicit data type of the value of each pixel channel

See also: isValid(), isReadOnly().

◆ frameType()

const FrameType & Ocean::Frame::frameType ( ) const

inline

Returns the frame type of this frame.

This return value is actually the cast of the base class of this frame.

Returns: Frame type

◆ hasAlphaChannel()

bool Ocean::Frame::hasAlphaChannel ( ) const

inline

Returns whether the frame's pixel format contains an alpha channel.

Returns: True, if so

◆ hasTransparentPixel() [1/3]

template<typename T >

bool Ocean::Frame::hasTransparentPixel ( const T opaque ) const

Returns whether the frame holds at least one pixel with an non opaque alpha value.

The pixel format must be composed of one plane only.

Returns: True, if so

Template Parameters

T	The type of the frame's data type, either `uint8_t`, or `uint16_t`

◆ hasTransparentPixel() [2/3]

template<>

bool Ocean::Frame::hasTransparentPixel ( const uint16_t opaque ) const

inline

◆ hasTransparentPixel() [3/3]

template<>

bool Ocean::Frame::hasTransparentPixel ( const uint8_t opaque ) const

inline

◆ haveIntersectingMemory()

bool Ocean::Frame::haveIntersectingMemory ( const Frame & frame ) const

Returns whether two frame objects have any amount of intersecting memory.

This frame and the given frame must both be valid.
Use this function to ensure that e.g., a source buffer and target buffer is completely independent.
This functions also considers memory intersections in the padding area as regular intersection.

Parameters

frame The second frame of which its memory will be compared to the memory of this frame, must be valid

Returns: True, if so

◆ isContinuous()

bool Ocean::Frame::isContinuous ( ) const

inline

Returns whether all planes of this frame have continuous memory and thus do not contain any padding at the end of their rows.

Returns: True, if so

◆ isOwner()

bool Ocean::Frame::isOwner ( ) const

inline

Returns whether the frame is the owner of the internal frame data.

Otherwise the frame data is stored by e.g., a 3rd party and this frame holds a reference only.
The frame is not owner of the memory if at least one plane is not owner of the memory.

Returns: True, if so

See also: Plane::isOwner().

◆ isPlaneContinuous()

bool Ocean::Frame::isPlaneContinuous ( const unsigned int planeIndex = 0u ) const

inline

Returns whether a specific plane of this frame is based on continuous memory and thus does not have any padding at the end of rows.

Parameters

planeIndex The index of the plane for which the check is done, with range [0, planes().size())

Returns: True, if so

◆ isPlaneOwner()

bool Ocean::Frame::isPlaneOwner ( const unsigned int planeIndex = 0u ) const

inline

Returns whether a specific plane of this frame is the owner of the memory.

Parameters

planeIndex The index of the plane for which the check is done, with range [0, planes().size())

Returns: True, if so

◆ isReadOnly()

bool Ocean::Frame::isReadOnly ( ) const

inline

Returns true, if the frame allows only read access (using constdata()).

Otherwise, data() may be used to modify the frame data. Beware: Call this method only if the frame is valid. The frame is read-only if at least one plane is read-only.

Returns: True, if the frame object allows read access only

See also: data(), constdata(), Plane::isReadOnly().

◆ isValid()

bool Ocean::Frame::isValid ( ) const

inline

Returns whether this frame is valid.

This function is mainly callying FrameType::isValid(), while in debug builds, addtional checks are performed.

Returns: True, if so

◆ makeContinuous()

void Ocean::Frame::makeContinuous ( )

Makes the memory of this frame continuous.

If the memory is already continuous, nothing happens.
If the memory is not continuous, a new continuous memory block will be allocated and the memory is copied into the new memory block (for each plane individually), the frame will be owner of the memory.

◆ makeOwner()

void Ocean::Frame::makeOwner ( )

Makes this frame the owner of the memory.

In case this frame does not own the memory, new memory will be allocated.

◆ operator bool()

Ocean::Frame::operator bool ( ) const

inlineexplicit

Returns whether this frame object is valid and holds a frame.

Returns: True, if so

◆ operator=() [1/2]

Frame& Ocean::Frame::operator= ( const Frame & right )

noexcept

Assign operator.

Releases the current frame (and frees the memory if the frame is the owner) and creates a second version of a given frame. If the given source frame is not owner of the frame data, this frame will also not be owner of the frame data.
But, if the given source frame is the owner of the frame data, this frame will also be the owner of new copy of the frame data.
If the memory is actually copied, the memory layout of this new frame will be continuous. This function behaves similar like the normal copy constructor.

Parameters

right The right frame to assign

Returns: Reference to this frame

◆ operator=() [2/2]

Frame& Ocean::Frame::operator= ( Frame && right )

noexcept

Move operator.

Parameters

right The right frame to moved

Returns: Reference to this frame

◆ paddingBytes()

unsigned int Ocean::Frame::paddingBytes ( const unsigned int planeIndex = 0u ) const

inline

Returns the optional number of padding bytes at the end of each row for a specific plane.

Parameters

planeIndex The index of the plane for which the number of padding bytes will be returned, with range [0, planes().size())

Returns: The frame's number of padding bytes, in bytes, with range [0, infinity)

◆ paddingElements()

unsigned int Ocean::Frame::paddingElements ( const unsigned int planeIndex = 0u ) const

inline

Returns the optional number of padding elements at the end of each row for a specific plane.

Parameters

planeIndex The index of the plane for which the number of padding elements will be returned, with range [0, planes().size())

Returns: The frame's number of padding elements, in elements, with range [0, infinity)

◆ pixel()

template<typename T >

T * Ocean::Frame::pixel	(	const unsigned int	x,
		const unsigned int	y,
		const unsigned int	planeIndex = `0u`
	)

inline

Returns the pointer to the data of a specific pixel.

Ensure that the frame is valid and that the frame holds a valid frame buffer before this function is called.

In general, the usage of this function is recommended for prototyping only.
As the location of each pixel has to be calculated every time, this function is quite slow.
Production code should use the constdata(), data(), constrow(), and row() functions instead.

The vertical location (the y coordinate) of the pixel is defined with respect to the origin of the frame's data.
Therefore, pixel(0, 0) will return the top left pixel of an image if pixelOrigin() == ORIGIN_UPPER_LEFT,
and will return the bottom left pixel of an image if pixelOrigin() == ORIGIN_LOWER_LEFT.
In any case, pixel(0, 0) is equivalent to data().

This function most not be called for packed pixel formats.

Parameters

x	The horizontal position of the requested pixel, with range [0, planeWidth(planeIndex) - 1]
y	The vertical position of the requested pixel, with range [0, planeHeight(planeIndex) - 1]
planeIndex	The index of the plane for which the pixel will be returned, with range [0, planes().size())

Returns: The pointer to the memory at which the pixel starts

Template Parameters

T	The explicit data type of the value of each pixel channel

See also: data(), row(), constpixel(), constdata(), constrow(). formatIsPacked().

The following code snippet shows how this function may be used:

// we create a RGB image with 24 bit per pixel (8 bit per channel)
Frame rgbImage(FrameType(1280u, 720u, FrameType::FORMAT_RGB24, FrameType::ORIGIN_UPPER_LEFT));
 
const uint8_t redChannelValue = 0xFF; // 255
const uint8_t greenChannelValue = 0x80; // 128
const uint8_t blueChannelValue = 0x00; // 0
 
// we iterate overall every pixel
for (unsigned int y = 0u; y < rgbImage.height(); ++y)
{
    for (unsigned int x = 0u; x < rgbImage.width(); ++x)
    {
        // we store the pointer to the pixel
        uint8_t* rgbPixel = rgbImage.pixel<uint8_t>(x, y);
 
        // we set the color value of each red channel and green channel
        rgbPixel[0] = redChannelValue;
        rgbPixel[1] = greenChannelValue;
 
        // we also can set the value of each channel directly
        rgbImage.pixel<uint8_t>(x, y)[2] = blueChannelValue;
    }
}
 
// now we have set the color of every pixel of the image

◆ planeBytesPerPixel()

unsigned int Ocean::Frame::planeBytesPerPixel ( const unsigned int planeIndex ) const

inline

Returns the number of bytes of one pixel of a plane for a pixel format.

Beware: This function will return 0 if the pixel format is a special packed format (e.g., FORMAT_Y10_PACKED) which does not allow to calculate the number of bytes per pixel.

Parameters

planeIndex The index of the plane for which the bytes per pixel will be returned, with range [0, numberPlanes(imagePixelFormat))

Returns: The plane's number of bytes per pixel, will be 0 for special packed pixel formats like FORMAT_Y10_PACKED

◆ planeChannels()

unsigned int Ocean::Frame::planeChannels ( const unsigned int planeIndex ) const

inline

Returns the channels of a plane of this frame.

Parameters

planeIndex The index of the plane for which the channels will be returned, with range [0, planes().size())

Returns: The plane's channels, with range [0, infinity)

◆ planeHeight()

unsigned int Ocean::Frame::planeHeight ( const unsigned int planeIndex ) const

inline

Returns the height of a plane of this frame.

Parameters

planeIndex The index of the plane for which the height will be returned, with range [0, planes().size())

Returns: The plane's height, in pixel, with range [0, infinity)

◆ planes()

const Frame::Planes & Ocean::Frame::planes ( ) const

inline

Returns the individual planes of this frame.

Returns: The frame's plane

◆ planeWidth()

unsigned int Ocean::Frame::planeWidth ( const unsigned int planeIndex ) const

inline

Returns the width of a plane of this frame.

Parameters

planeIndex The index of the plane for which the width will be returned, with range [0, planes().size())

Returns: The plane's width, in pixel, with range [0, infinity)

◆ planeWidthBytes()

unsigned int Ocean::Frame::planeWidthBytes ( const unsigned int planeIndex ) const

inline

Returns the width of a plane of this frame, not in pixel, but in bytes, not including padding at the end of each plane row.

Parameters

planeIndex The index of the plane for which the width will be returned, with range [0, planes().size())

Returns: The plane's width, in bytes, with range [0, infinity)

◆ planeWidthElements()

unsigned int Ocean::Frame::planeWidthElements ( const unsigned int planeIndex ) const

inline

Returns the width of a plane of this frame, not in pixel, but in elements, not including padding at the end of each plane row.

Parameters

planeIndex The index of the plane for which the width will be returned, with range [0, planes().size())

Returns: The plane's width, in elements, with is planeWidth(planeIndex) * planeChannels(planeIndex), with range [0, infinity)

◆ relativeTimestamp()

const Timestamp & Ocean::Frame::relativeTimestamp ( ) const

inline

Returns the relative timestamp of this frame.

Returns: Timestamp

◆ release()

void Ocean::Frame::release ( )

Releases this frame and the frame data if this frame is the owner.

◆ row()

template<typename T >

T * Ocean::Frame::row	(	const unsigned int	y,
		const unsigned int	planeIndex = `0u`
	)

inline

Returns the pointer to the pixel data of a specific row.

Ensure that the frame is valid and that the frame holds a valid frame buffer before this function is called.

The index of the row is defined with respect to the origin of the frame's data.
Therefore, row<T>(0) will return the top row of an image if pixelOrigin() == ORIGIN_UPPER_LEFT,
and will return the bottom row of an image if pixelOrigin() == ORIGIN_LOWER_LEFT.
In any case, row<T>(0) is equivalent to data<T>().

Parameters

y	The index of the row (the vertical location) to which the resulting pointer will point, with range [0, planeHeight(planeIndex) - 1]
planeIndex	The index of the plane for which the pixel will be returned, with range [0, planes().size())

Returns: The pointer to the memory at which the row starts

Template Parameters

T	The explicit data type of the value of each pixel channel

See also: data(), pixel(), constrow(), constdata(), constpixel().

◆ set()

bool Ocean::Frame::set	(	const FrameType &	frameType,
		const bool	forceOwner,
		const bool	forceWritable = `false`,
		const Indices32 &	planePaddingElements = `Indices32()`,
		const Timestamp &	timestamp = `Timestamp(false)`,
		bool *	reallocated = `nullptr`
	)

Sets a new frame type for this frame.

The frame data will be reallocated (re-initialized) if the specified frame types, or one of the property flags (forceOwner, forceWritable) do not fit with the current frame.

Parameters

frameType	New frame type to set, can be invalid
forceOwner	If specified and the frame is not yet owner, then the frame will allocate its own frame buffer
forceWritable	If specified and the frame is read-only, then the frame will allocate its own frame buffer
planePaddingElements	The padding elements at the end of each individual plane row, in elements, one for each plane, an empty vector to use the existing padding layout or no padding if reallocation
timestamp	The timestamp to be set
reallocated	Optional resulting state whether the frame has been reallocated; nullptr otherwise

Returns: True, if succeeded

◆ setRelativeTimestamp()

void Ocean::Frame::setRelativeTimestamp ( const Timestamp & relative )

inline

Sets the relative timestamp of this frame.

In contrast to the standard timestamp of this frame, the relative timestamp provides the frame time in relation to a reference time.

Parameters

relative The relative timestamp to be set

See also: setTimestamp().

◆ setTimestamp()

void Ocean::Frame::setTimestamp ( const Timestamp & timestamp )

inline

Sets the timestamp of this frame.

Parameters

timestamp Timestamp to be set

See also: setRelativeTimestamp().

◆ setValue() [1/4]

template<typename T , const unsigned int tPlaneChannels>

bool Ocean::Frame::setValue	(	const PixelType< T, tPlaneChannels > &	planePixelValue,
		const unsigned int	planeIndex = `0u`
	)

Sets the memory of the frame to a specified pixel value (the memory of one plane).

Each pixel will be set to the same values (each channel will be set to an own value).

The following code snippet shows how this function may be used:

Frame rgbFrame(FrameType(1920u, 1080u, FrameType::FORMAT_RGB24, FrameType::ORIGIN_UPPER_LEFT));
const Frame::PixelType<uint8_t, 3u> yellow({0xFFu, 0xFFu, 0x00u});
rgbFrame.setValue<uint8_t, 3u>(yellow);
 
Frame tensorFrame(FrameType(1920u, 1080u, FrameType::genericPixelFormat<float, 3u>(), FrameType::ORIGIN_UPPER_LEFT));
const Frame::PixelType<float, 3u> value({0.0f, 1.0f, 2.0f});
tensorFrame.setValue<float, 3u>(value);

Parameters

planePixelValue	The pixel value to be set to each pixel
planeIndex	The index of the plane for which the memory will be set, with range [0, numberPlanes())

Template Parameters

T	The data type of the given pixel value, must be identical to the data type of the frame
tPlaneChannels	The number of channels the plane has (not the number of channels the frame has), with range [1, channels()]

Returns: True, if the image data was writable; False, if the image holds read-only memory

◆ setValue() [2/4]

template<typename T >

bool Ocean::Frame::setValue	(	const std::initializer_list< typename Identity< T >::Type > &	planePixelValues,
		const unsigned int	planeIndex = `0u`
	)

Sets the memory of the frame to a specified pixel value (the memory of one plane).

Each pixel will be set to the same values (each channel will be set to an own value).

The following code snippet shows how this function may be used:

Frame rgbFrame(FrameType(1920u, 1080u, FrameType::FORMAT_RGB24, FrameType::ORIGIN_UPPER_LEFT));
rgbFrame.setValue<uint8_t>({0xFFu, 0xFFu, 0x00u});
 
Frame tensorFrame(FrameType(1920u, 1080u, FrameType::genericPixelFormat<float, 3u>(), FrameType::ORIGIN_UPPER_LEFT));
tensorFrame.setValue<float>({0.0f, 1.0f, 2.0f});

Parameters

planePixelValues	The pixel values to be set to each pixel, one value for each plane channel
planeIndex	The index of the plane for which the memory will be set, with range [0, numberPlanes())

Template Parameters

T	The data type of the given pixel value, must be identical to the data type of the frame

Returns: True, if the image data was writable; False, if the image holds read-only memory

◆ setValue() [3/4]

template<typename T >

bool Ocean::Frame::setValue	(	const T *	planePixelValue,
		const size_t	planePixelValueSize,
		const unsigned int	planeIndex = `0u`
	)

Sets the memory of the frame to a specified pixel value (the memory of one plane).

Each pixel will be set to the same values (each channel will be set to an own value).

The following code snippet shows how this function may be used:

Frame rgbFrame(FrameType(1920u, 1080u, FrameType::FORMAT_RGB24, FrameType::ORIGIN_UPPER_LEFT));

rgbFrame.setValue<uint8_t>(CV::Canvas::yellow(), 3u);

Ocean::CV::Canvas::yellow

static const uint8_t * yellow(const FrameType::PixelFormat pixelFormat=FrameType::FORMAT_RGB24)

Returns the color values for a yellow color.

Parameters

planePixelValue	The pixel value to be set to each pixel, one value for each plane channel, must be valid
planePixelValueSize	The number of provided pixel values, with range [1, 4], must be `planes().channels()`
planeIndex	The index of the plane for which the memory will be set, with range [0, numberPlanes())

Template Parameters

T	The data type of the given pixel value, must be identical to the data type of the frame

Returns: True, if the image data was writable; False, if the image holds read-only memory

◆ setValue() [4/4]

bool Ocean::Frame::setValue	(	const uint8_t	value,
		const unsigned int	planeIndex = `0u`,
		const bool	skipPaddingData = `true`
	)

Sets the memory of the frame to a specified byte value (the memory of one plane).

Each byte of the frame's memory will be set to the same value.

The following code snippet shows how this function may be used:

Frame rgbFrame(FrameType(1920u, 1080u, FrameType::FORMAT_RGB24, FrameType::ORIGIN_UPPER_LEFT));

rgbFrame.setValue(0x00u);

Parameters

value	The 8 bit value to be set to each byte of the frame, with range [0, 255]
planeIndex	The index of the plane for which the memory will be set, with range [0, numberPlanes())
skipPaddingData	True, to do not set the memory value of the padding data; False, to write the memory value of the padding data as well

Returns: True, if the image data was writable; False, if the image holds read-only memory

See also: isReadOnly().

◆ size()

unsigned int Ocean::Frame::size ( const unsigned int planeIndex = 0u ) const

inline

Returns the number of bytes necessary for a specific plane including optional padding at the end of plane rows.

Parameters

planeIndex The index of the plane for which the check is done, with range [0, planes().size())

Returns: Frame buffer size in bytes, with range [0, infinity)

◆ strideBytes()

unsigned int Ocean::Frame::strideBytes ( const unsigned int planeIndex = 0u ) const

inline

Returns the number of bytes within one row, including optional padding at the end of a row for a specific plane.

Parameters

planeIndex The index of the plane for which the number of stride bytes will be returned, with range [0, planes().size())

Returns: The frame's stride defined in bytes, with range [pixels * elementsPerPixel * bitsPerDatatype() / 8, infinity)

◆ strideBytes2paddingElements()

static bool Ocean::Frame::strideBytes2paddingElements	(	const PixelFormat &	pixelFormat,
		const unsigned int	imageWidth,
		const unsigned int	planeStrideBytes,
		unsigned int &	planePaddingElements,
		const unsigned int	planeIndex = `0u`
	)

static

Determines the number of padding elements at the end of a row of a plane for which the pixel format, the image width and the plane's stride (in bytes) are known.

Parameters

pixelFormat	The pixel format of the image, must be valid
imageWidth	The width of the image in pixels, with range [0, infinity)
planeStrideBytes	The number of bytes between to start points of successive rows (the stride of the row in bytes) for the specified image plane, with range [planeWidthBytes(planeIndex), infinity)
planePaddingElements	The resulting number of padding elements at the end of each row (at the actual end of the row's pixel data) for the specified image plane, in elements (not bytes), with range [0, infinity)
planeIndex	The index of the image plane for which the number of padding elements will be calculated, with range [0, numberPlanes() - 1]

Returns: True, if succeeded; False, if the given plane configuration is invalid

◆ strideElements()

unsigned int Ocean::Frame::strideElements ( const unsigned int planeIndex = 0u ) const

inline

Returns the number of elements within one row, including optional padding at the end of a row for a specific plane.

The number of elements per row is be determined by the plane's values: pixels * elementsPerPixel + paddingElements().

Parameters

planeIndex The index of the plane for which the number of stride elements will be returned, with range [0, planes().size())

Returns: The frame's stride defined in elements, with range [width * elementsPerPixel, infinity)

◆ subFrame()

Frame Ocean::Frame::subFrame	(	const unsigned int	subFrameLeft,
		const unsigned int	subFrameTop,
		const unsigned int	subFrameWidth,
		const unsigned int	subFrameHeight,
		const CopyMode	copyMode = `CM_USE_KEEP_LAYOUT`
	)		const

Returns a sub-frame of this frame.

The copy mode defines whether the resulting sub-frame owns the memory or uses the memory.

Parameters

subFrameLeft	Left start location of the resulting sub-frame, in pixels, defined within this frame, with range [0, width - 1], must be 0 if the pixel format is packed
subFrameTop	Top start location of the resulting sub-frame, in pixels, defined within this frame, with range [0, height - 1]
subFrameWidth	Width of the resulting sub-frame in pixels, with range [1, width() - subFrameLeft]
subFrameHeight	Height of the resulting sub-frame in pixels, with range [1, height() - subFrameTop]
copyMode	The copy mode to be applied, must not be CM_COPY_KEEP_LAYOUT_COPY_PADDING_DATA

Returns: The requested sub-frame not owning the image data, an invalid frame if the defined sub-region does not fit into this frame

See also: FrameType::formatIsPacked().

◆ timestamp()

const Timestamp & Ocean::Frame::timestamp ( ) const

inline

Returns the timestamp of this frame.

Returns: Timestamp

◆ updateMemory() [1/3]

template<typename T >

bool Ocean::Frame::updateMemory ( const std::initializer_list< T * > & planeDatas )

Updates the memory pointers for all or some of the planes of the frame to new writable memory locations.

This function should be used only when the planes do not own their memory, to maintain consistent ownership behavior across the frame.

Parameters

planeDatas The new writable memory pointers to be set, the number of pointers provided should be at least one and at most equal to numberPlanes().

Returns: True, if succeeded; False, if e.g., the plane to update owned the memory

See also: isPlaneOwner().

◆ updateMemory() [2/3]

template<typename T >

bool Ocean::Frame::updateMemory	(	const T *	data,
		const unsigned int	planeIndex = `0u`
	)

Updates the memory pointer for a specific plane of the frame to a new read-only memory location.

This function should only be used if the specified plane does not own its memory to ensure that the frame's ownership behavior remains consistent.

Parameters

data	The new read-only memory pointer to be set, must be valid
planeIndex	The index of the frame's plane for which the memory will be updated, with range [0, numberPlanes())

Returns: True, if succeeded; False, if e.g., the plane to update owned the memory

See also: isPlaneOwner().

◆ updateMemory() [3/3]

template<typename T >

bool Ocean::Frame::updateMemory	(	T *	data,
		const unsigned int	planeIndex = `0u`
	)

Updates the memory pointer for a specific plane of the frame to a new read-only or writable memory location.

This function should only be used if the specified plane currently does not own its memory to ensure that the frame's ownership behavior remains consistent. For read-only memory, provide a const memory pointer; For writable memory, provide a non-const pointer.

Parameters

data	The new writable memory pointer to be set, must be valid
planeIndex	The index of the frame's plane for which the memory will be updated, with range [0, numberPlanes())

Returns: True, if succeeded; False, if e.g., the plane to update owned the memory

See also: isPlaneOwner().

Field Documentation

◆ planes_

Planes Ocean::Frame::planes_

protected

The individual memory planes of this frame.

◆ relativeTimestamp_

Timestamp Ocean::Frame::relativeTimestamp_

protected

Relative timestamp of this frame.

◆ timestamp_

Timestamp Ocean::Frame::timestamp_

protected

Timestamp of the frame.

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

Frame.h

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ PixelType

◆ PlaneInitializers

◆ Planes

Member Enumeration Documentation

◆ AdvancedCopyMode

◆ CopyMode

Constructor & Destructor Documentation

◆ Frame() [1/20]

◆ Frame() [2/20]

◆ Frame() [3/20]

◆ Frame() [4/20]

◆ Frame() [5/20]

◆ Frame() [6/20]

◆ Frame() [7/20]

◆ Frame() [8/20]

◆ Frame() [9/20]

◆ ~Frame()

◆ Frame() [10/20]

◆ Frame() [11/20]

◆ Frame() [12/20]

◆ Frame() [13/20]

◆ Frame() [14/20]

◆ Frame() [15/20]

◆ Frame() [16/20]

◆ Frame() [17/20]

◆ Frame() [18/20]

◆ Frame() [19/20]

◆ Frame() [20/20]

Member Function Documentation

◆ constdata()

◆ constpixel()

◆ constrow()

◆ containsValue()

◆ copy() [1/2]

◆ copy() [2/2]

◆ data()

◆ frameType()

◆ hasAlphaChannel()

◆ hasTransparentPixel() [1/3]

◆ hasTransparentPixel() [2/3]

◆ hasTransparentPixel() [3/3]

◆ haveIntersectingMemory()

◆ isContinuous()

◆ isOwner()

◆ isPlaneContinuous()

◆ isPlaneOwner()

◆ isReadOnly()

◆ isValid()

◆ makeContinuous()

◆ makeOwner()

◆ operator bool()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ paddingBytes()

◆ paddingElements()

◆ pixel()

◆ planeBytesPerPixel()

◆ planeChannels()

◆ planeHeight()

◆ planes()

◆ planeWidth()

◆ planeWidthBytes()

◆ planeWidthElements()

◆ relativeTimestamp()

◆ release()

◆ row()

◆ set()

◆ setRelativeTimestamp()

◆ setTimestamp()

◆ setValue() [1/4]

◆ setValue() [2/4]