1 /*
2 * Copyright (c) 2020 The WebRTC project authors. All Rights Reserved.
3 *
4 * Use of this source code is governed by a BSD-style license
5 * that can be found in the LICENSE file in the root of the source
6 * tree. An additional intellectual property rights grant can be found
7 * in the file PATENTS. All contributing project authors may
8 * be found in the AUTHORS file in the root of the source tree.
9 */
10 #ifndef MODULES_VIDEO_CODING_SVC_SCALABLE_VIDEO_CONTROLLER_H_
11 #define MODULES_VIDEO_CODING_SVC_SCALABLE_VIDEO_CONTROLLER_H_
12
13 #include <vector>
14
15 #include "absl/container/inlined_vector.h"
16 #include "api/transport/rtp/dependency_descriptor.h"
17 #include "api/video/video_bitrate_allocation.h"
18 #include "common_video/generic_frame_descriptor/generic_frame_info.h"
19
20 namespace webrtc {
21
22 // Controls how video should be encoded to be scalable. Outputs results as
23 // buffer usage configuration for encoder and enough details to communicate the
24 // scalability structure via dependency descriptor rtp header extension.
25 class ScalableVideoController {
26 public:
27 struct StreamLayersConfig {
28 int num_spatial_layers = 1;
29 int num_temporal_layers = 1;
30 // Indicates if frames can reference frames of a different resolution.
31 bool uses_reference_scaling = true;
32 // Spatial layers scaling. Frames with spatial_id = i expected to be encoded
33 // with original_resolution * scaling_factor_num[i] / scaling_factor_den[i].
34 int scaling_factor_num[DependencyDescriptor::kMaxSpatialIds] = {1, 1, 1, 1};
35 int scaling_factor_den[DependencyDescriptor::kMaxSpatialIds] = {1, 1, 1, 1};
36 };
37 class LayerFrameConfig {
38 public:
39 // Builders/setters.
40 LayerFrameConfig& Id(int value);
41 LayerFrameConfig& Keyframe();
42 LayerFrameConfig& S(int value);
43 LayerFrameConfig& T(int value);
44 LayerFrameConfig& Reference(int buffer_id);
45 LayerFrameConfig& Update(int buffer_id);
46 LayerFrameConfig& ReferenceAndUpdate(int buffer_id);
47
48 // Getters.
Id()49 int Id() const { return id_; }
IsKeyframe()50 bool IsKeyframe() const { return is_keyframe_; }
SpatialId()51 int SpatialId() const { return spatial_id_; }
TemporalId()52 int TemporalId() const { return temporal_id_; }
Buffers()53 const absl::InlinedVector<CodecBufferUsage, kMaxEncoderBuffers>& Buffers()
54 const {
55 return buffers_;
56 }
57
58 private:
59 // Id to match configuration returned by NextFrameConfig with
60 // (possibly modified) configuration passed back via OnEncoderDone.
61 // The meaning of the id is an implementation detail of
62 // the ScalableVideoController.
63 int id_ = 0;
64
65 // Indication frame should be encoded as a key frame. In particular when
66 // `is_keyframe=true` property `CodecBufferUsage::referenced` should be
67 // ignored and treated as false.
68 bool is_keyframe_ = false;
69
70 int spatial_id_ = 0;
71 int temporal_id_ = 0;
72 // Describes how encoder which buffers encoder allowed to reference and
73 // which buffers encoder should update.
74 absl::InlinedVector<CodecBufferUsage, kMaxEncoderBuffers> buffers_;
75 };
76
77 virtual ~ScalableVideoController() = default;
78
79 // Returns video structure description for encoder to configure itself.
80 virtual StreamLayersConfig StreamConfig() const = 0;
81
82 // Returns video structure description in format compatible with
83 // dependency descriptor rtp header extension.
84 virtual FrameDependencyStructure DependencyStructure() const = 0;
85
86 // Notifies Controller with updated bitrates per layer. In particular notifies
87 // when certain layers should be disabled.
88 // Controller shouldn't produce LayerFrameConfig for disabled layers.
89 virtual void OnRatesUpdated(const VideoBitrateAllocation& bitrates) = 0;
90
91 // When `restart` is true, first `LayerFrameConfig` should have `is_keyframe`
92 // set to true.
93 // Returned vector shouldn't be empty.
94 virtual std::vector<LayerFrameConfig> NextFrameConfig(bool restart) = 0;
95
96 // Returns configuration to pass to EncoderCallback.
97 virtual GenericFrameInfo OnEncodeDone(const LayerFrameConfig& config) = 0;
98 };
99
100 // Below are implementation details.
101 inline ScalableVideoController::LayerFrameConfig&
Id(int value)102 ScalableVideoController::LayerFrameConfig::Id(int value) {
103 id_ = value;
104 return *this;
105 }
106 inline ScalableVideoController::LayerFrameConfig&
Keyframe()107 ScalableVideoController::LayerFrameConfig::Keyframe() {
108 is_keyframe_ = true;
109 return *this;
110 }
111 inline ScalableVideoController::LayerFrameConfig&
S(int value)112 ScalableVideoController::LayerFrameConfig::S(int value) {
113 spatial_id_ = value;
114 return *this;
115 }
116 inline ScalableVideoController::LayerFrameConfig&
T(int value)117 ScalableVideoController::LayerFrameConfig::T(int value) {
118 temporal_id_ = value;
119 return *this;
120 }
121 inline ScalableVideoController::LayerFrameConfig&
Reference(int buffer_id)122 ScalableVideoController::LayerFrameConfig::Reference(int buffer_id) {
123 buffers_.emplace_back(buffer_id, /*referenced=*/true, /*updated=*/false);
124 return *this;
125 }
126 inline ScalableVideoController::LayerFrameConfig&
Update(int buffer_id)127 ScalableVideoController::LayerFrameConfig::Update(int buffer_id) {
128 buffers_.emplace_back(buffer_id, /*referenced=*/false, /*updated=*/true);
129 return *this;
130 }
131 inline ScalableVideoController::LayerFrameConfig&
ReferenceAndUpdate(int buffer_id)132 ScalableVideoController::LayerFrameConfig::ReferenceAndUpdate(int buffer_id) {
133 buffers_.emplace_back(buffer_id, /*referenced=*/true, /*updated=*/true);
134 return *this;
135 }
136
137 } // namespace webrtc
138
139 #endif // MODULES_VIDEO_CODING_SVC_SCALABLE_VIDEO_CONTROLLER_H_
140