This is the base class for all frame mediums. More...

Inheritance diagram for Ocean::Media::FrameMedium:

Data Structures
class	FrameReceiver
	This class implements a simpler receiver for frames which can be used with the frame callback functionality of FrameMedium. More...

class	MediaFrameType
	Definition of a media frame type composed by the frame dimension, pixel format, pixel origin and a frame frequency. More...

class	SortableFrameType
	Class allowing the sorting of several frame media types according their popularity. More...

Public Types
typedef double	FrameFrequency
	Definition of a frame frequency defined in Hz. More...

typedef std::function< void(const Frame &frame, const SharedAnyCamera &camera)>	FrameCallbackFunction
	Definition of a callback function for frame events. More...

typedef ScopedSubscriptionHandler::ScopedSubscriptionType	FrameCallbackScopedSubscription
	Definition of a subscription object for frame callback events. More...

Public Types inherited from Ocean::Media::Medium
enum	Type : uint32_t { MEDIUM = 0u , FRAME_MEDIUM = 1u << 0u , SOUND_MEDIUM = 1u << 1u , FINITE_MEDIUM = 1u << 2u , LIVE_MEDIUM = 1u << 3u , CONFIG_MEDIUM = 1u << 4u , AUDIO = (1u << 5u) \| FINITE_MEDIUM \| SOUND_MEDIUM , IMAGE = (1u << 6u) \| FRAME_MEDIUM , PIXEL_IMAGE = (1u << 7u) \| FRAME_MEDIUM , BUFFER_IMAGE = (1u << 8u) \| FRAME_MEDIUM , IMAGE_SEQUENCE = (1u << 9u) \| FRAME_MEDIUM \| FINITE_MEDIUM , LIVE_AUDIO = (1u << 10u) \| LIVE_MEDIUM \| SOUND_MEDIUM , LIVE_VIDEO = (1u << 11u) \| LIVE_MEDIUM \| FRAME_MEDIUM , MICROPHONE = (1u << 12u) \| LIVE_MEDIUM , MOVIE = (1u << 13u) \| FINITE_MEDIUM \| FRAME_MEDIUM \| SOUND_MEDIUM }
	Definition of different medium types. More...

Public Member Functions
	~FrameMedium () override
	Destructs a frame object. More...

bool	hasFrame () const
	Returns whether the object holds a frame. More...

FrameFrequency	frameFrequency () const
	Returns the frequency of the frame in Hz. More...

virtual FrameRef	frame (SharedAnyCamera *anyCamera=nullptr) const
	Returns the most recent frame. More...

virtual FrameRef	frame (const Timestamp timestamp, SharedAnyCamera *anyCamera=nullptr) const
	Returns the frame with a specific timestamp. More...

virtual FrameRef	frameTimeout (const double timeout, SharedAnyCamera *anyCamera=nullptr) const
	Waits until the first frame is available. More...

virtual bool	hasFrame (const Timestamp timestamp) const
	Returns whether this media object currently holds a frame with specified timestamp. More...

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

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

FrameType::PixelFormat	preferredFramePixelFormat () const
	Returns the preferred frame pixel format. More...

FrameFrequency	preferredFrameFrequency () const
	Returns the preferred frame frequency in Hz. More...

virtual HomogenousMatrixD4	device_T_camera () const
	Returns the transformation between the camera and device. More...

virtual bool	setPreferredFrameDimension (const unsigned int width, const unsigned int height)
	Sets the preferred frame dimension. More...

virtual bool	setPreferredFramePixelFormat (const FrameType::PixelFormat format)
	Sets the preferred frame pixel format. More...

virtual bool	setPreferredFrameFrequency (const FrameFrequency frequency)
	Sets the preferred frame frequency in Hz. More...

size_t	capacity () const
	Returns the capacity of the frame history of this frame medium object. More...

bool	setCapacity (const size_t capacity)
	Sets or changes the capacity of the frame history of this frame medium object. More...

FrameCallbackScopedSubscription	addFrameCallback (FrameCallbackFunction &&frameCallbackFunction)
	Adds a callback function which is called whenever a new frame arrives. More...

Public Member Functions inherited from Ocean::Media::Medium
const std::string &	url () const
	Returns the url of the medium. More...

bool	isValid () const
	Returns whether the medium is valid. More...

const std::string &	library () const
	Returns the name of the owner library. More...

Type	type () const
	Returns the type of the medium. More...

bool	isType (const Type type) const
	Returns whether a medium has a given type. More...

virtual bool	isStarted () const =0
	Returns whether the medium is started currently. More...

bool	isExclusive () const
	Returns whether this medium can be use exclusively. More...

virtual bool	start ()=0
	Starts the medium. More...

virtual bool	pause ()=0
	Pauses the medium. More...

virtual bool	stop ()=0
	Stops the medium. More...

virtual Timestamp	startTimestamp () const =0
	Returns the start timestamp. More...

virtual Timestamp	pauseTimestamp () const =0
	Returns the pause timestamp. More...

virtual Timestamp	stopTimestamp () const =0
	Returns the stop timestamp. More...

virtual MediumRef	clone () const
	Clones this medium and returns a new independent instance of this medium. More...

Static Public Member Functions
static bool	syncedFrames (const FrameMediumRefs &frameMediums, const Timestamp lastTimestamp, FrameRefs &frames, SharedAnyCameras &cameras, const unsigned int waitTime=2u, bool timedOut=nullptr, HomogenousMatricesD4 device_T_cameras=nullptr)
	Extracts most recent frames from several frame medium objects and ensures that the timestamps of all frames are identical. More...

Static Public Member Functions inherited from Ocean::Media::Medium
static std::string	convertType (const Type type)
	Converts a medium type to a unique string. More...

static Type	convertType (const std::string &type)
	Converts a medium type string to a medium type. More...

Protected Types
typedef ScopedSubscriptionCallbackHandlerT< FrameCallbackFunction, FrameMedium, true >	FrameCallbackHandler
	Definition of a thread-safe subscription handler for frame callback functions. More...

typedef std::vector< MediaFrameType >	FrameTypes
	Definition of a vector holding frame types. More...

Protected Member Functions
	FrameMedium (const std::string &url)
	Creates a new frame medium by a given url. More...

virtual bool	deliverNewFrame (Frame &&frame, SharedAnyCamera &&anyCamera=SharedAnyCamera())
	Delivers a new frame to this FrameMedium. More...

Protected Member Functions inherited from Ocean::Media::Medium
	Medium (const Medium &medium)=delete
	Disabled copy constructor. More...

	Medium (const std::string &url)
	Creates a new medium by a given url. More...

virtual	~Medium ()
	Destructs a medium. More...

Medium &	operator= (const Medium &medium)=delete
	Disabled copy operator. More...

Protected Attributes
FrameCollection	frameCollection_
	Frame collection storing several frames with different timestamps. More...

FrameCallbackHandler	frameCallbackHandler_
	The handler for frame callback functions. More...

FrameFrequency	recentFrameFrequency_ = FrameFrequency(0)
	Frame frequency. More...

MediaFrameType	preferredFrameType_
	Preferred frame type of the medium. More...

Protected Attributes inherited from Ocean::Media::Medium
std::string	url_
	Url of the medium. More...

std::string	libraryName_
	Name of the owner library. More...

bool	isValid_ = false
	Determines whether the medium is valid. More...

Type	type_ = MEDIUM
	Type of the medium. More...

Lock	lock_
	Medium lock. More...

Detailed Description

This is the base class for all frame mediums.

Member Typedef Documentation

◆ FrameCallbackFunction

typedef std::function<void(const Frame& frame, const SharedAnyCamera& camera)> Ocean::Media::FrameMedium::FrameCallbackFunction

Definition of a callback function for frame events.

Parameters

frame	The event's frame, will be valid
camera	The camera profile associated with the frame, invalid if unknown

◆ FrameCallbackHandler

typedef ScopedSubscriptionCallbackHandlerT<FrameCallbackFunction, FrameMedium, true> Ocean::Media::FrameMedium::FrameCallbackHandler

protected

Definition of a thread-safe subscription handler for frame callback functions.

◆ FrameCallbackScopedSubscription

typedef ScopedSubscriptionHandler::ScopedSubscriptionType Ocean::Media::FrameMedium::FrameCallbackScopedSubscription

Definition of a subscription object for frame callback events.

◆ FrameFrequency

typedef double Ocean::Media::FrameMedium::FrameFrequency

Definition of a frame frequency defined in Hz.

◆ FrameTypes

typedef std::vector<MediaFrameType> Ocean::Media::FrameMedium::FrameTypes

protected

Definition of a vector holding frame types.

Constructor & Destructor Documentation

◆ ~FrameMedium()

Ocean::Media::FrameMedium::~FrameMedium ( )

override

Destructs a frame object.

◆ FrameMedium()

Ocean::Media::FrameMedium::FrameMedium ( const std::string & url )

explicitprotected

Creates a new frame medium by a given url.

Parameters

url	Url of the frame medium

Member Function Documentation

◆ addFrameCallback()

FrameCallbackScopedSubscription Ocean::Media::FrameMedium::addFrameCallback ( FrameCallbackFunction && frameCallbackFunction )

Adds a callback function which is called whenever a new frame arrives.

If at least one callback is registered, this frame medium will not store any frame in the internal frame store.

Parameters

frameCallbackFunction The callback function to be added, must be valid

Returns: The subscription object, the callback function will exist as long as the subscription object exists

See also: frame()

◆ capacity()

size_t Ocean::Media::FrameMedium::capacity ( ) const

Returns the capacity of the frame history of this frame medium object.

Returns: The capacity of frames, with range [1, infinity)

◆ deliverNewFrame()

virtual bool Ocean::Media::FrameMedium::deliverNewFrame	(	Frame &&	frame,
		SharedAnyCamera &&	anyCamera = `SharedAnyCamera()`
	)

protectedvirtual

Delivers a new frame to this FrameMedium.

The new frame will either be stored in the medium's frame collection or forwarded to subscribed frame callback functions.

Parameters

frame	The new frame to deliver, must be valid
anyCamera	The camera profile associated with the frame, invalid if unknown

Returns: True, if succeeded

◆ device_T_camera()

virtual HomogenousMatrixD4 Ocean::Media::FrameMedium::device_T_camera ( ) const

virtual

Returns the transformation between the camera and device.

The device can be either a webcam, a mobile phone, or any other device delivering visual information. The transformation between camera and device represents the offset translation and orientation between the camera sensor and the device (e.g., the display of the device).
The device coordinate system has the origin in the center of the device (e.g., the display) and the Z-axis is pointing out towards the user.
The camera coordinate system has the origin in the center of the camera (center of projection) and the negative Z-axis is pointing towards the scene.

         device top
...........................
.                         .                          camera
.         ^               .                   ---------------------------------
.       Y |               .                  |               ^                 |
.         |               .                  |             Y |                 |
.         |               .                  |               |                 |
.         O --------->    .                  |               |                 |
.        /        X       .                  |               O --------->      |
.       / Z               .                  |              /        X         |
.      v                  .                  |             / Z                 |
.                         .                  |            v                    |
...........................                   ---------------------------------
.      home button        .
...........................
     device bottom

Reimplemented in Ocean::Media::PixelImage, Ocean::Media::AVFoundation::AVFLiveVideo, Ocean::Media::Android::ALiveVideo, and Ocean::Media::Android::ALiveVideo.

◆ frame() [1/2]

virtual FrameRef Ocean::Media::FrameMedium::frame	(	const Timestamp	timestamp,
		SharedAnyCamera *	anyCamera = `nullptr`
	)		const

virtual

Returns the frame with a specific timestamp.

If no frame exists with the given timestamp the most recent frame is returned.

Parameters

timestamp	The timestamp of the frame to return
anyCamera	Optional resulting camera profile of the frame, if known

Returns: Requested frame

See also: hasFrame().

◆ frame() [2/2]

virtual FrameRef Ocean::Media::FrameMedium::frame ( SharedAnyCamera * anyCamera = nullptr ) const

virtual

Returns the most recent frame.

Parameters

anyCamera Optional resulting camera profile of the frame, if known

Returns: Most recent frame

◆ frameFrequency()

FrameMedium::FrameFrequency Ocean::Media::FrameMedium::frameFrequency ( ) const

inline

Returns the frequency of the frame in Hz.

Returns: Frequency of the frame in Hz

◆ frameTimeout()

virtual FrameRef Ocean::Media::FrameMedium::frameTimeout	(	const double	timeout,
		SharedAnyCamera *	anyCamera = `nullptr`
	)		const

virtual

Waits until the first frame is available.

If the time to wait is exceeded and no frame is available, no frame is returned.

Parameters

timeout	Time to wait for the first frame, in seconds, with range [0, infinity)
anyCamera	Optional resulting camera profile of the frame, if known

Returns: Frame if available

◆ hasFrame() [1/2]

bool Ocean::Media::FrameMedium::hasFrame ( ) const

inline

Returns whether the object holds a frame.

Returns: True, if so

◆ hasFrame() [2/2]

virtual bool Ocean::Media::FrameMedium::hasFrame ( const Timestamp timestamp ) const

virtual

Returns whether this media object currently holds a frame with specified timestamp.

Beware: There is no guarantee that the frame will be available after this call due to multi-thread issues!

Parameters

timestamp The timestamp to be checked

Returns: True, if so

◆ preferredFrameFrequency()

FrameMedium::FrameFrequency Ocean::Media::FrameMedium::preferredFrameFrequency ( ) const

inline

Returns the preferred frame frequency in Hz.

Returns: Preferred frame frequency in Hz

See also: setPreferredFrameFrequency().

◆ preferredFrameHeight()

unsigned int Ocean::Media::FrameMedium::preferredFrameHeight ( ) const

inline

Returns the preferred height of the frame in pixel.

Returns: Preferred frame height

See also: setPreferredFrameDiminsion(), preferredFrameWidth().

◆ preferredFramePixelFormat()

FrameType::PixelFormat Ocean::Media::FrameMedium::preferredFramePixelFormat ( ) const

inline

Returns the preferred frame pixel format.

Returns: Preferred pixel format

See also: setPreferredFramePixelFormat().

◆ preferredFrameWidth()

unsigned int Ocean::Media::FrameMedium::preferredFrameWidth ( ) const

inline

Returns the preferred width of the frame in pixel.

Returns: Preferred frame width

See also: setPreferredFrameDiminsion(), preferredFrameHeight().

◆ setCapacity()

bool Ocean::Media::FrameMedium::setCapacity ( const size_t capacity )

Sets or changes the capacity of the frame history of this frame medium object.

Parameters

capacity The capacity to set, with range [1, infinity)

Returns: True, if succeeded

◆ setPreferredFrameDimension()

virtual bool Ocean::Media::FrameMedium::setPreferredFrameDimension	(	const unsigned int	width,
		const unsigned int	height
	)

virtual

Sets the preferred frame dimension.

Beware: There is no guarantee that this dimension can be provided.

Parameters

width	Preferred frame width in pixel
height	Preferred frame height in pixel

Returns: True, if the medium accepts this preferred values.

See also: preferredFrameWidth(), preferredFrameHeight().

Reimplemented in Ocean::Media::MediaFoundation::MFFrameMedium, and Ocean::Media::DirectShow::DSFrameMedium.

◆ setPreferredFrameFrequency()

virtual bool Ocean::Media::FrameMedium::setPreferredFrameFrequency ( const FrameFrequency frequency )

virtual

Sets the preferred frame frequency in Hz.

Beware: There is no guarantee that this frequency can be provided.

Parameters

frequency Preferred frequency in Hz

Returns: True, if the medium accepts this preferred value.

See also: preferredFrameFrequency().

Reimplemented in Ocean::Media::MediaFoundation::MFFrameMedium, Ocean::Media::ImageSequence, and Ocean::Media::DirectShow::DSFrameMedium.

◆ setPreferredFramePixelFormat()

virtual bool Ocean::Media::FrameMedium::setPreferredFramePixelFormat ( const FrameType::PixelFormat format )

virtual

Sets the preferred frame pixel format.

Beware: There is no guarantee that this pixel format can be provided.

Parameters

format Preferred pixel format

Returns: True, if the medium accepts this preferred value.

See also: preferredFramePixelFormat().

Reimplemented in Ocean::Media::OpenImageLibraries::OILBufferImage, Ocean::Media::WIC::WICBufferImage, Ocean::Media::MediaFoundation::MFFrameMedium, Ocean::Media::ImageSequence, Ocean::Media::ImageIO::IIOBufferImage, and Ocean::Media::DirectShow::DSFrameMedium.

◆ syncedFrames()

static bool Ocean::Media::FrameMedium::syncedFrames	(	const FrameMediumRefs &	frameMediums,
		const Timestamp	lastTimestamp,
		FrameRefs &	frames,
		SharedAnyCameras &	cameras,
		const unsigned int	waitTime = `2u`,
		bool *	timedOut = `nullptr`,
		HomogenousMatricesD4 *	device_T_cameras = `nullptr`
	)

static

Extracts most recent frames from several frame medium objects and ensures that the timestamps of all frames are identical.

Parameters

frameMediums	The frame medium objects from which the frames will be extracted, at least one
lastTimestamp	The timestamp of the last extracted frames to accept frames with newer timestamp only, an invalid timestamp to accept any frame
frames	The resulting frames with identical timestamp, one for each frame medium object
cameras	The resulting camera profiles, one for each frame medium object
waitTime	The wait time in milliseconds this function will wait until it fails if not all frame medium objects can provide the expected frame
timedOut	Optional resulting True in case the function timed out when waiting for all synced frames; nullptr if not of interest
device_T_cameras	Optional resulting transformations between camera and device, one for each frame medium object; nullptr if not of interest

Returns: True, if succeeded

Field Documentation

◆ frameCallbackHandler_

FrameCallbackHandler Ocean::Media::FrameMedium::frameCallbackHandler_

protected

The handler for frame callback functions.

◆ frameCollection_

FrameCollection Ocean::Media::FrameMedium::frameCollection_

protected

Frame collection storing several frames with different timestamps.

◆ preferredFrameType_

MediaFrameType Ocean::Media::FrameMedium::preferredFrameType_

protected

Preferred frame type of the medium.

◆ recentFrameFrequency_

FrameFrequency Ocean::Media::FrameMedium::recentFrameFrequency_ = FrameFrequency(0)

protected

Frame frequency.

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

FrameMedium.h

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ FrameCallbackFunction

◆ FrameCallbackHandler

◆ FrameCallbackScopedSubscription

◆ FrameFrequency

◆ FrameTypes

Constructor & Destructor Documentation

◆ ~FrameMedium()

◆ FrameMedium()

Member Function Documentation

◆ addFrameCallback()

◆ capacity()

◆ deliverNewFrame()

◆ device_T_camera()

◆ frame() [1/2]

◆ frame() [2/2]

◆ frameFrequency()

◆ frameTimeout()

◆ hasFrame() [1/2]

◆ hasFrame() [2/2]

◆ preferredFrameFrequency()

◆ preferredFrameHeight()

◆ preferredFramePixelFormat()

◆ preferredFrameWidth()

◆ setCapacity()

◆ setPreferredFrameDimension()

◆ setPreferredFrameFrequency()

◆ setPreferredFramePixelFormat()

◆ syncedFrames()

Field Documentation

◆ frameCallbackHandler_

◆ frameCollection_

◆ preferredFrameType_

◆ recentFrameFrequency_