luna_mobile_online/include/tsdk/IStream.h

#pragma once

#include "ITrackCallbacks.h"

#include <fsdk/IObject.h>
#include <fsdk/Types/Image.h>

namespace tsdk {

	struct IStream : fsdk::IRefCounted {

		/** @brief Stream statistics
		*/
		struct Statistics {
			//! total pushed frames count (count of frames, that were tried to push via pushFrame)
			size_t totalFramesCount = 0;

			//! count of frames, that were successfully added to the processing queue (that frames, for which pushFrame returned true)
			size_t pushedFramesCount = 0;

			//! count of frames, that were used only to update frg (w/o tracks processing)
			size_t onlyFRGUpdateFramesCount = 0;

			//! count of frames, that were used to process tracks
			size_t tracksProcessingFramesCount = 0;

			//! count of frames, that were successfully processed (must be equal to pushedFramesCount after stream has been finished)
			size_t processedFramesCount = 0;

			//! fps for last second
			uint32_t fps = 0;
		};

		/** @brief Pushes a single frame to the buffer.
		*	@note You should pass consequent frames for reasonble results 
		*	(thing video frames).
		*	Call face detector and tracker, then triggers the callback for 
		*	processed faces.
		*	@param frame input frame image. Supported image formats: R8G8B8 OR R8G8B8X8 for both MemoryCPU/MemoryGPU.
			For MemoryGPU also YUV_NV12 and YUV_NV21 are supported.
		*	@param frameId unique identifier for frames sequence.
		*	@param data is any additional data that a developer wants to receive in callbacks-realization.
		*	Do not use the delete-operator. The garbage collector is implemented inside TrackEngine for this param.
		*	@return true if frame was appended to the queue for processing,
		*	false otherwise - frame was skipped because of full queue.
		*/
		TRACK_ENGINE_API virtual bool pushFrame(
				const fsdk::Image &frame,
				uint32_t frameId,
			tsdk::AdditionalFrameData *data) = 0;

		/** @brief Pushes a single user defined custom frame to the buffer.
		*	@note see ICustomFrame for details
		*	@param frame custom frame
		*	@param frameId unique identifier for frames sequence.
		*	@param data is any additional data that a developer wants to receive in callbacks-realization.
		*	@note Now the feature is supported only for CPU memory residence!
		*	Do not use the delete-operator. The garbage collector is implemented inside TrackEngine for this param.
		*	@return true if frame was appended to the queue for processing,
		*	false otherwise - frame was skipped because of full queue.
		*/
		TRACK_ENGINE_API virtual bool pushCustomFrame(
			fsdk::Ref<tsdk::ICustomFrame> frame,
			uint32_t frameId,
			tsdk::AdditionalFrameData *data) = 0;

		/** @brief Pushes a single frame to the buffer with timeout.
		*	@note You should pass consequent frames for reasonble results
		*	(thing video frames).
		*	Call face detector and tracker, then triggers the callback for
		*	processed faces.
		*	This function may block for longer than timeMs due to
		*	scheduling, resource contention delays or changing system clock
		*	@param frame input frame image. Format must be R8G8B8. 
		*	@param frameId unique identifier for frames sequence.
		*	@param data is any additional data that a developer wants to receive in callbacks-realization.
		*	@note Now the feature is supported only for CPU memory residence!
		*	Do not use the delete-operator. The garbage collector is implemented inside TrackEngine for this param.
		*   @param timeMs the maximum time in milliseconds to spend waiting for execution.
		*	if timeMs is zero, then function's behavior is equal to pushFrame
		*	@return true if frame was appended to the queue for processing,
		*	false otherwise - frame was skipped because of full queue (after waiting timeMs milliseconds).
		*/
		TRACK_ENGINE_API virtual bool pushFrameWaitFor(
			const fsdk::Image &frame,
			uint32_t frameId,
			tsdk::AdditionalFrameData *data,
			uint32_t timeMs) = 0;

		/** @brief  Pushes a single user defined custom frame to the buffer.
		*	@note @see 'pushCustomFrame', 'pushFrameWaitFor' for details
		*/
		TRACK_ENGINE_API virtual bool pushCustomFrameWaitFor(
			fsdk::Ref<tsdk::ICustomFrame> frame,
			uint32_t frameId,
			tsdk::AdditionalFrameData *data,
			uint32_t timeMs) = 0;

		/** @brief Sets a best shot observer for this Stream
		*	@param observer pointer to the observer object, @see IBestShotObserver
		*/
		TRACK_ENGINE_API virtual void
			TSDK_DEPRECATED("This call is deprecated. Consider "
			"ITrackEngine::setBatchBestShotObserver(tsdk::IBatchBestShotObserver *observer) call\n")
			setBestShotObserver(tsdk::IBestShotObserver* observer) = 0;

		/** @brief Sets a visual observer for this Stream
		*	@param observer pointer to the observer object, @see IVisualObserver
		*/
		TRACK_ENGINE_API virtual void
			TSDK_DEPRECATED("This call is deprecated. Consider "
				"ITrackEngine::setBatchVisualObserver(tsdk::IBatchVisualObserver *observer) call\n")
			setVisualObserver(tsdk::IVisualObserver* observer) = 0;

		/** @brief Sets a debug observer for this Stream
		*	@param observer pointer to the observer object, @see IDebugObserver
		*/
		TRACK_ENGINE_API virtual void
			TSDK_DEPRECATED("This call is deprecated. Consider "
				"ITrackEngine::setBatchDebugObserver(tsdk::IBatchDebugObserver *observer) call\n")
			setDebugObserver(tsdk::IDebugObserver* observer) = 0;

		/** @brief Sets a best shot predicate for this Stream
		*  @param predicate best shot predicate, @see IBestShotPredicate
		*/
		TRACK_ENGINE_API virtual void setBestShotPredicate(
				tsdk::IBestShotPredicate* predicate) = 0;

		/** @brief Sets a visual predicate for this Stream
		*  @param predicate visual predicate, @see IVisualPredicate
		*/
		TRACK_ENGINE_API virtual void setVisualPredicate(
			tsdk::IVisualPredicate *predicate) = 0;

		/** @brief Enables or disables observer
		*	@param type observer type
		*	@param enabled enable observer if true, disable otherwise
		*/
		TRACK_ENGINE_API virtual void setObserverEnabled(
			tsdk::StreamObserverType type, bool enabled) = 0;

		/** @brief Blocks current thread until all frames in this Stream will be handled
		 *  and all callbacks will be executed.
		 *  @note Stream could not be used after join.
		 *  @see setBestShotObserver, setVisualObserver, setDebugObserver and
		 *  setBestShotPredicate
		 */
		TRACK_ENGINE_API virtual void join() = 0;

		/** @brief Get stream statistics (see above: struct Statistics)
		*	@return stream statistics
		*/
		TRACK_ENGINE_API virtual Statistics getStatistics() const = 0;

		/** @brief Get stream id
		*	@return stream Id
		*/
		TRACK_ENGINE_API virtual const StreamId& getId() const = 0;

		/** @brief Get stream parameters, @see ITrackEngine::createStream and StreamParams for details
		*	@return stream parameters
		*/
		TRACK_ENGINE_API virtual StreamParams getParams() const = 0;
	};
}