Ocean
Loading...
Searching...
No Matches
LiveVideo.h
Go to the documentation of this file.
1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 *
4 * This source code is licensed under the MIT license found in the
5 * LICENSE file in the root directory of this source tree.
6 */
7
8#ifndef META_OCEAN_MEDIA_LIVE_VIDEO_H
9#define META_OCEAN_MEDIA_LIVE_VIDEO_H
10
11#include "ocean/media/Media.h"
14
15namespace Ocean
16{
17
18namespace Media
19{
20
21// Forward declaration.
22class LiveVideo;
23
24/**
25 * Definition of a smart medium reference holding a live video object.
26 * @see SmartMediumRef, LiveVideo.
27 * @ingroup media
28 */
30
31/**
32 * This class is the base class for all live videos.
33 * @ingroup media
34 */
35class OCEAN_MEDIA_EXPORT LiveVideo :
36 public virtual FrameMedium,
37 public virtual LiveMedium
38{
39 public:
40
41 /**
42 * Definition of individual control modes.
43 * The modes are used for exposure, ISO, and focus.
44 */
45 enum ControlMode : uint32_t
46 {
47 /// An invalid control mode.
48 CM_INVALID = 0u,
49 /// The control is fixed (e.g., because the exposure, ISO, or focus was set manually).
51 /// The control is dynamic (e.g., because auto exposure, ISO, or focus is enabled).
52 CM_DYNAMIC
53 };
54
55 /**
56 * Definition of a vector holding control modes.
57 */
58 using ControlModes = std::vector<ControlMode>;
59
60 /**
61 * Definition of individual stream types.
62 */
63 enum StreamType : uint32_t
64 {
65 /// An invalid stream type.
66 ST_INVALID = 0u,
67 /// A stream composed of individual uncompressed frames with individual pixel formats (e.g., FORMAT_RGB24, FORMAT_YUYV16, etc.).
69 /// A stream composed of Motion JPEG frames.
71 /// A stream composed of compressed frames with individual codecs (e.g., H264, H265).
72 ST_CODEC
73 };
74
75 /**
76 * Definition of a vector holding stream types.
77 */
78 using StreamTypes = std::vector<StreamType>;
79
80 /**
81 * Definition of individual codec types.
82 */
83 enum CodecType : uint32_t
84 {
85 /// An invalid codec type.
86 CT_INVALID = 0u,
87 /// Codec using H.264 for encoding or decoding.
89 /// Codec using H.265 for encoding or decoding.
90 CT_H265
91 };
92
93 /**
94 * This class holds the relevant information describing the property of a stream.
95 */
96 class OCEAN_MEDIA_EXPORT StreamProperty
97 {
98 public:
99
100 /**
101 * Simple helper struct allowing to calculate a hash value for stream property.
102 */
103 struct Hash
104 {
105 /**
106 * Returns a hash value for a StreamProperty object.
107 * @param streamProperty The object for which the hash will be returned
108 * @return The hash value
109 */
110 inline size_t operator()(const StreamProperty& streamProperty) const;
111 };
112
113 public:
114
115 /**
116 * Default constructor creating an invalid object.
117 */
118 StreamProperty() = default;
119
120 /**
121 * Creates a new stream property object.
122 * @param streamType The type of the stream
123 * @param width The width of the stream in pixel
124 * @param height The height of the stream in pixel
125 * @param framePixelFormat The pixel format of the stream, invalid if stream type is not ST_FRAME
126 * @param codecType The type of the stream, invalid if stream type is not ST_CODEC
127 */
128 StreamProperty(const StreamType streamType, const unsigned int width, unsigned int height, const FrameType::PixelFormat framePixelFormat, const CodecType codecType);
129
130 /**
131 * Returns whether this configuration object holds a valid configuration.
132 * The configuration is valid if a valid stream type and a valid image resolution is defined.
133 * @return True, if so
134 */
135 inline bool isValid() const;
136
137 /**
138 * Returns whether this configuration object holds the same configuration as the given one.
139 * @param right The configuration object to compare
140 * @return True, if so
141 */
142 bool operator==(const StreamProperty& right) const;
143
144 public:
145
146 /// The type of the stream.
147 StreamType streamType_ = ST_INVALID;
148
149 /// The width of the stream in pixel.
150 unsigned int width_ = 0u;
151
152 /// The height of the stream in pixel.
153 unsigned int height_ = 0u;
154
155 /// The pixel format of the stream, only valid if the stream type is ST_FRAME.
156 FrameType::PixelFormat framePixelFormat_ = FrameType::FORMAT_UNDEFINED;
157
158 /// The codec of the stream, only valid if the stream type is ST_CODEC.
159 CodecType codecType_ = CT_INVALID;
160 };
161
162 /**
163 * This class holds the relevant information describing a video stream configuration.
164 */
165 class OCEAN_MEDIA_EXPORT StreamConfiguration : public StreamProperty
166 {
167 public:
168
169 /**
170 * Default constructor creating an invalid object.
171 */
173
174 /**
175 * Creates a new stream configuration object.
176 * @param streamProperty The property of the stream
177 * @param frameRates The frame rates of the stream in Hz
178 */
179 StreamConfiguration(const StreamProperty& streamProperty, std::vector<double>&& frameRates);
180
181 /**
182 * Creates a new stream configuration object.
183 * @param streamType The type of the stream
184 * @param width The width of the stream in pixel
185 * @param height The height of the stream in pixel
186 * @param frameRates The frame rates of the stream in Hz
187 * @param framePixelFormat The pixel format of the stream, invalid if stream type is not ST_FRAME
188 * @param codecType The type of the stream, invalid if stream type is not ST_CODEC
189 */
190 StreamConfiguration(const StreamType streamType, const unsigned int width, unsigned int height, std::vector<double>&& frameRates, const FrameType::PixelFormat framePixelFormat, const CodecType codecType);
191
192 /**
193 * Returns a string containing the readable information of this stream configuration.
194 * @return The readable information of this stream configuration
195 */
196 std::string toString() const;
197
198 public:
199
200 /// The frame rates of the stream in Hz.
201 std::vector<double> frameRates_;
202 };
203
204 /**
205 * Definition of a vector holding stream configurations.
206 */
207 using StreamConfigurations = std::vector<StreamConfiguration>;
208
209 public:
210
211 /**
212 * Returns the supported stream types.
213 * @return The types of all supported streams, empty if this object does not allow (or does not need) to select the stream type.
214 */
216
217 /**
218 * Returns the supported stream configurations for a given stream type.
219 * @param streamType The type of the stream for which the supported stream configurations will be returned, ST_INVALID to return all stream configurations for all stream types
220 * @return The supported stream configurations
221 */
222 virtual StreamConfigurations supportedStreamConfigurations(const StreamType streamType = ST_INVALID) const;
223
224 /**
225 * Returns the current exposure duration of this device.
226 * @param minDuration Optional resulting minimal duration to set, in seconds, with range (0, infinity), -1 if unknown
227 * @param maxDuration Optional resulting maximal duration to set, in seconds, with range [minDuration, infinity), -1 if unknown
228 * @param exposureMode Optional resulting exposure mode, nullptr if not of interest
229 * @return The duration in seconds, with range [minDuration, maxDuration], -1 if unknown
230 * @see setExposureDuration().
231 */
232 virtual double exposureDuration(double* minDuration = nullptr, double* maxDuration = nullptr, ControlMode* exposureMode = nullptr) const;
233
234 /**
235 * Returns the current ISO of this device.
236 * @param minISO Optional resulting minimal ISO to set, with range (0, infinity), -1 if unknown
237 * @param maxISO Optional resulting maximal ISO to set, with range (0, infinity), -1 if unknown
238 * @param isoMode Optional resulting ISO mode, nullptr if not of interest
239 * @return The current ISO, with range [minISO, maxISO], -1 if unknown
240 */
241 virtual float iso(float* minISO = nullptr, float* maxISO = nullptr, ControlMode* isoMode = nullptr) const;
242
243 /**
244 * Returns the current focus of this device.
245 * @return The device's focus, with range [0, 1] with 0 shortest distance and 1 furthest distance
246 * @param focusMode Optional resulting focus mode, nullptr if not of interest
247 */
248 virtual float focus(ControlMode* focusMode = nullptr) const;
249
250 /**
251 * Returns whether video stabilization is currently enabled.
252 * Video stabilization applies post-processing to reduce camera shake, which may introduce artificial warping or geometric distortions.
253 * @return True, if video stabilization is enabled; False, if video stabilization is disabled; depends on platform and device support
254 */
255 virtual bool videoStabilization() const;
256
257 /**
258 * Sets the preferred stream type.
259 * There is no guarantee that the device will use this stream type.
260 * @param streamType The preferred stream type to be set, must be valid
261 * @return True, if succeeded
262 * @see setPreferredStreamConfiguration().
263 */
264 virtual bool setPreferredStreamType(const StreamType streamType);
265
266 /**
267 * Sets the preferred stream configuration.
268 * Using this function will forward some settings to the underlying FrameMedium object via setPreferredFrameDimension(), setPreferredFramePixelFormat(), and setPreferredFrameFrequency().
269 * There is no guarantee that the device will use this stream type.
270 * @param streamConfiguration The preferred stream configuration to be set, must be valid
271 * @return True, if succeeded
272 * @see setPreferredStreamType(), FrameMedium::setPreferredFrameDimension(), FrameMedium::setPreferredFramePixelFormat(), and FrameMedium::setPreferredFrameFrequency()
273 */
274 virtual bool setPreferredStreamConfiguration(const StreamConfiguration& streamConfiguration);
275
276 /**
277 * Sets the exposure duration of this device.
278 * @param duration The exposure duration to be set, in seconds, with range (0, infinity), 0 for auto exposure, -1 for a one-time auto exposure
279 * @param allowShorterExposure True, to allow shorter exposure durations than the specified duration; False, to enforce the specified duration; Ignored if auto exposure is used
280 * @return True, if succeeded
281 * @see exposureDuration().
282 */
283 virtual bool setExposureDuration(const double duration, const bool allowShorterExposure = false);
284
285 /**
286 * Sets the ISO of this device.
287 * @param iso The ISO to be set, with range (0, infinity), -1 for auto ISO
288 * @return True, if succeeded
289 * @see iso().
290 */
291 virtual bool setISO(const float iso);
292
293 /**
294 * Sets the focus of this device.
295 * @param position The focus position to be set, with range [0, 1] with 0 shortest distance and 1 furthest distance, -1 for auto focus
296 * @return True, if succeeded
297 * @see focus().
298 */
299 virtual bool setFocus(const float position);
300
301 /**
302 * Sets whether video stabilization should be enabled.
303 * Video stabilization applies post-processing to reduce camera shake, but may introduce artificial warping or geometric distortions.
304 * Disabling video stabilization provides raw, unprocessed camera frames.
305 * @param enable True, to enable video stabilization; False, to disable video stabilization and get raw camera data
306 * @return True, if succeeded; False, if video stabilization control is not supported on this platform or device
307 * @see videoStabilization().
308 */
309 virtual bool setVideoStabilization(const bool enable);
310
311 /**
312 * Translates a control mode to a string.
313 * @param controlMode The control mode to translate
314 * @return The translated string, 'Invalid' if the control mode is invalid or unknown
315 */
316 static std::string translateControlMode(const ControlMode controlMode);
317
318 /**
319 * Translates a stream type to a string.
320 * @param streamType The stream type to be translated
321 * @return The translated string, 'Invalid' if the stream type is invalid or unknown
322 */
323 static std::string translateStreamType(const StreamType streamType);
324
325 /**
326 * Translates a codec type to a string.
327 * @param codecType The stream type to be translated
328 * @return The translated string, 'Invalid' if the codec type is invalid or unknown
329 */
330 static std::string translateCodecType(const CodecType codecType);
331
332 protected:
333
334 /**
335 * Creates a new live video source by a given url.
336 * @param url Url of the live video source
337 */
338 explicit LiveVideo(const std::string& url);
339};
340
341inline size_t LiveVideo::StreamProperty::Hash::operator()(const StreamProperty& streamProperty) const
342{
343 size_t seed = std::hash<StreamType>{}(streamProperty.streamType_);
344 seed ^= std::hash<unsigned int>{}(streamProperty.width_) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
345 seed ^= std::hash<unsigned int>{}(streamProperty.height_) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
346 seed ^= std::hash<FrameType::PixelFormat>{}(streamProperty.framePixelFormat_) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
347 seed ^= std::hash<CodecType>{}(streamProperty.codecType_) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
348
349 return seed;
350}
351
353{
354 return streamType_ != ST_INVALID && width_ > 0u && height_ > 0u;
355}
356
357}
358
359}
360
361#endif // META_OCEAN_MEDIA_LIVE_VIDEO_H
PixelFormat
Definition of all pixel formats available in the Ocean framework.
Definition Frame.h:183
This is the base class for all frame mediums.
Definition FrameMedium.h:53
This class it the base class for all live mediums.
Definition LiveMedium.h:38
This class holds the relevant information describing a video stream configuration.
Definition LiveVideo.h:166
std::vector< double > frameRates_
The frame rates of the stream in Hz.
Definition LiveVideo.h:201
std::string toString() const
Returns a string containing the readable information of this stream configuration.
StreamConfiguration(const StreamProperty &streamProperty, std::vector< double > &&frameRates)
Creates a new stream configuration object.
StreamConfiguration()=default
Default constructor creating an invalid object.
StreamConfiguration(const StreamType streamType, const unsigned int width, unsigned int height, std::vector< double > &&frameRates, const FrameType::PixelFormat framePixelFormat, const CodecType codecType)
Creates a new stream configuration object.
This class holds the relevant information describing the property of a stream.
Definition LiveVideo.h:97
FrameType::PixelFormat framePixelFormat_
The pixel format of the stream, only valid if the stream type is ST_FRAME.
Definition LiveVideo.h:156
StreamProperty(const StreamType streamType, const unsigned int width, unsigned int height, const FrameType::PixelFormat framePixelFormat, const CodecType codecType)
Creates a new stream property object.
CodecType codecType_
The codec of the stream, only valid if the stream type is ST_CODEC.
Definition LiveVideo.h:159
StreamProperty()=default
Default constructor creating an invalid object.
StreamType streamType_
The type of the stream.
Definition LiveVideo.h:147
unsigned int height_
The height of the stream in pixel.
Definition LiveVideo.h:153
unsigned int width_
The width of the stream in pixel.
Definition LiveVideo.h:150
bool operator==(const StreamProperty &right) const
Returns whether this configuration object holds the same configuration as the given one.
bool isValid() const
Returns whether this configuration object holds a valid configuration.
Definition LiveVideo.h:352
This class is the base class for all live videos.
Definition LiveVideo.h:38
virtual double exposureDuration(double *minDuration=nullptr, double *maxDuration=nullptr, ControlMode *exposureMode=nullptr) const
Returns the current exposure duration of this device.
CodecType
Definition of individual codec types.
Definition LiveVideo.h:84
@ CT_H264
Codec using H.264 for encoding or decoding.
Definition LiveVideo.h:88
LiveVideo(const std::string &url)
Creates a new live video source by a given url.
virtual bool setPreferredStreamType(const StreamType streamType)
Sets the preferred stream type.
virtual bool setExposureDuration(const double duration, const bool allowShorterExposure=false)
Sets the exposure duration of this device.
virtual bool videoStabilization() const
Returns whether video stabilization is currently enabled.
virtual StreamConfigurations supportedStreamConfigurations(const StreamType streamType=ST_INVALID) const
Returns the supported stream configurations for a given stream type.
StreamType
Definition of individual stream types.
Definition LiveVideo.h:64
@ ST_INVALID
An invalid stream type.
Definition LiveVideo.h:66
@ ST_MJPEG
A stream composed of Motion JPEG frames.
Definition LiveVideo.h:70
@ ST_FRAME
A stream composed of individual uncompressed frames with individual pixel formats (e....
Definition LiveVideo.h:68
ControlMode
Definition of individual control modes.
Definition LiveVideo.h:46
@ CM_FIXED
The control is fixed (e.g., because the exposure, ISO, or focus was set manually).
Definition LiveVideo.h:50
std::vector< ControlMode > ControlModes
Definition of a vector holding control modes.
Definition LiveVideo.h:58
virtual bool setVideoStabilization(const bool enable)
Sets whether video stabilization should be enabled.
virtual bool setFocus(const float position)
Sets the focus of this device.
virtual bool setISO(const float iso)
Sets the ISO of this device.
std::vector< StreamConfiguration > StreamConfigurations
Definition of a vector holding stream configurations.
Definition LiveVideo.h:207
virtual StreamTypes supportedStreamTypes() const
Returns the supported stream types.
static std::string translateControlMode(const ControlMode controlMode)
Translates a control mode to a string.
virtual bool setPreferredStreamConfiguration(const StreamConfiguration &streamConfiguration)
Sets the preferred stream configuration.
virtual float iso(float *minISO=nullptr, float *maxISO=nullptr, ControlMode *isoMode=nullptr) const
Returns the current ISO of this device.
std::vector< StreamType > StreamTypes
Definition of a vector holding stream types.
Definition LiveVideo.h:78
static std::string translateStreamType(const StreamType streamType)
Translates a stream type to a string.
static std::string translateCodecType(const CodecType codecType)
Translates a codec type to a string.
virtual float focus(ControlMode *focusMode=nullptr) const
Returns the current focus of this device.
This class implements a smart medium reference.
Definition MediumRef.h:33
SmartMediumRef< LiveVideo > LiveVideoRef
Definition of a smart medium reference holding a live video object.
Definition LiveVideo.h:29
The namespace covering the entire Ocean framework.
Definition Accessor.h:15
Simple helper struct allowing to calculate a hash value for stream property.
Definition LiveVideo.h:104
size_t operator()(const StreamProperty &streamProperty) const
Returns a hash value for a StreamProperty object.
Definition LiveVideo.h:341