1 /* 2 * Copyright 2019 The libgav1 Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef LIBGAV1_SRC_OBU_PARSER_H_ 18 #define LIBGAV1_SRC_OBU_PARSER_H_ 19 20 #include <array> 21 #include <cstddef> 22 #include <cstdint> 23 #include <memory> 24 #include <type_traits> 25 #include <utility> 26 27 #include "src/buffer_pool.h" 28 #include "src/decoder_state.h" 29 #include "src/gav1/decoder_buffer.h" 30 #include "src/gav1/status_code.h" 31 #include "src/utils/compiler_attributes.h" 32 #include "src/utils/constants.h" 33 #include "src/utils/memory.h" 34 #include "src/utils/raw_bit_reader.h" 35 #include "src/utils/types.h" 36 #include "src/utils/vector.h" 37 38 namespace libgav1 { 39 40 // structs and enums related to Open Bitstream Units (OBU). 41 42 enum { 43 kMinimumMajorBitstreamLevel = 2, 44 kSelectScreenContentTools = 2, 45 kSelectIntegerMv = 2, 46 kLoopRestorationTileSizeMax = 256, 47 kGlobalMotionAlphaBits = 12, 48 kGlobalMotionTranslationBits = 12, 49 kGlobalMotionTranslationOnlyBits = 9, 50 kGlobalMotionAlphaPrecisionBits = 15, 51 kGlobalMotionTranslationPrecisionBits = 6, 52 kGlobalMotionTranslationOnlyPrecisionBits = 3, 53 kMaxTileWidth = 4096, 54 kMaxTileArea = 4096 * 2304, 55 kPrimaryReferenceNone = 7, 56 // A special value of the scalability_mode_idc syntax element that indicates 57 // the picture prediction structure is specified in scalability_structure(). 58 kScalabilitySS = 14 59 }; // anonymous enum 60 61 struct ObuHeader { 62 ObuType type; 63 bool has_extension; 64 bool has_size_field; 65 int8_t temporal_id; 66 int8_t spatial_id; 67 }; 68 69 enum BitstreamProfile : uint8_t { 70 kProfile0, 71 kProfile1, 72 kProfile2, 73 kMaxProfiles 74 }; 75 76 // In the bitstream the level is encoded in five bits: the first three bits 77 // encode |major| - 2 and the last two bits encode |minor|. 78 // 79 // If the mapped level (major.minor) is in the tables in Annex A.3, there are 80 // bitstream conformance requirements on the maximum or minimum values of 81 // several variables. The encoded value of 31 (which corresponds to the mapped 82 // level 9.3) is the "maximum parameters" level and imposes no level-based 83 // constraints on the bitstream. 84 struct BitStreamLevel { 85 uint8_t major; // Range: 2-9. 86 uint8_t minor; // Range: 0-3. 87 }; 88 89 struct ColorConfig { 90 int8_t bitdepth; 91 bool is_monochrome; 92 ColorPrimary color_primary; 93 TransferCharacteristics transfer_characteristics; 94 MatrixCoefficients matrix_coefficients; 95 // A binary value (0 or 1) that is associated with the VideoFullRangeFlag 96 // variable specified in ISO/IEC 23091-4/ITUT H.273. 97 // * 0: the studio swing representation. 98 // * 1: the full swing representation. 99 ColorRange color_range; 100 int8_t subsampling_x; 101 int8_t subsampling_y; 102 ChromaSamplePosition chroma_sample_position; 103 bool separate_uv_delta_q; 104 }; 105 106 struct TimingInfo { 107 uint32_t num_units_in_tick; 108 uint32_t time_scale; 109 bool equal_picture_interval; 110 uint32_t num_ticks_per_picture; 111 }; 112 113 struct DecoderModelInfo { 114 uint8_t encoder_decoder_buffer_delay_length; 115 uint32_t num_units_in_decoding_tick; 116 uint8_t buffer_removal_time_length; 117 uint8_t frame_presentation_time_length; 118 }; 119 120 struct OperatingParameters { 121 uint32_t decoder_buffer_delay[kMaxOperatingPoints]; 122 uint32_t encoder_buffer_delay[kMaxOperatingPoints]; 123 bool low_delay_mode_flag[kMaxOperatingPoints]; 124 }; 125 126 struct ObuSequenceHeader { 127 // Section 7.5: 128 // Within a particular coded video sequence, the contents of 129 // sequence_header_obu must be bit-identical each time the sequence header 130 // appears except for the contents of operating_parameters_info. A new 131 // coded video sequence is required if the sequence header parameters 132 // change. 133 // 134 // IMPORTANT: ParametersChanged() is implemented with a memcmp() call. For 135 // this to work, this object and the |old| object must be initialized with 136 // an empty brace-enclosed list, which initializes any padding to zero bits. 137 // See https://en.cppreference.com/w/cpp/language/zero_initialization. 138 bool ParametersChanged(const ObuSequenceHeader& old) const; 139 140 BitstreamProfile profile; 141 bool still_picture; 142 bool reduced_still_picture_header; 143 int operating_points; 144 int operating_point_idc[kMaxOperatingPoints]; 145 BitStreamLevel level[kMaxOperatingPoints]; 146 int8_t tier[kMaxOperatingPoints]; 147 int8_t frame_width_bits; 148 int8_t frame_height_bits; 149 int32_t max_frame_width; 150 int32_t max_frame_height; 151 bool frame_id_numbers_present; 152 int8_t frame_id_length_bits; 153 int8_t delta_frame_id_length_bits; 154 bool use_128x128_superblock; 155 bool enable_filter_intra; 156 bool enable_intra_edge_filter; 157 bool enable_interintra_compound; 158 bool enable_masked_compound; 159 bool enable_warped_motion; 160 bool enable_dual_filter; 161 bool enable_order_hint; 162 // If enable_order_hint is true, order_hint_bits is in the range [1, 8]. 163 // If enable_order_hint is false, order_hint_bits is 0. 164 int8_t order_hint_bits; 165 // order_hint_shift_bits equals (32 - order_hint_bits) % 32. 166 // This is used frequently in GetRelativeDistance(). 167 uint8_t order_hint_shift_bits; 168 bool enable_jnt_comp; 169 bool enable_ref_frame_mvs; 170 bool choose_screen_content_tools; 171 int8_t force_screen_content_tools; 172 bool choose_integer_mv; 173 int8_t force_integer_mv; 174 bool enable_superres; 175 bool enable_cdef; 176 bool enable_restoration; 177 ColorConfig color_config; 178 bool timing_info_present_flag; 179 TimingInfo timing_info; 180 bool decoder_model_info_present_flag; 181 DecoderModelInfo decoder_model_info; 182 bool decoder_model_present_for_operating_point[kMaxOperatingPoints]; 183 bool initial_display_delay_present_flag; 184 uint8_t initial_display_delay[kMaxOperatingPoints]; 185 bool film_grain_params_present; 186 187 // IMPORTANT: the operating_parameters member must be at the end of the 188 // struct so that ParametersChanged() can be implemented with a memcmp() 189 // call. 190 OperatingParameters operating_parameters; 191 }; 192 // Verify it is safe to use offsetof with ObuSequenceHeader and to use memcmp 193 // to compare two ObuSequenceHeader objects. 194 static_assert(std::is_standard_layout<ObuSequenceHeader>::value, ""); 195 // Verify operating_parameters is the last member of ObuSequenceHeader. The 196 // second assertion assumes that ObuSequenceHeader has no padding after the 197 // operating_parameters field. The first assertion is a sufficient condition 198 // for ObuSequenceHeader to have no padding after the operating_parameters 199 // field. 200 static_assert(alignof(ObuSequenceHeader) == alignof(OperatingParameters), ""); 201 static_assert(sizeof(ObuSequenceHeader) == 202 offsetof(ObuSequenceHeader, operating_parameters) + 203 sizeof(OperatingParameters), 204 ""); 205 206 struct TileBuffer { 207 const uint8_t* data; 208 size_t size; 209 }; 210 211 enum MetadataType : uint8_t { 212 // 0 is reserved for AOM use. 213 kMetadataTypeHdrContentLightLevel = 1, 214 kMetadataTypeHdrMasteringDisplayColorVolume = 2, 215 kMetadataTypeScalability = 3, 216 kMetadataTypeItutT35 = 4, 217 kMetadataTypeTimecode = 5, 218 // 6-31 are unregistered user private. 219 // 32 and greater are reserved for AOM use. 220 }; 221 222 class ObuParser : public Allocable { 223 public: ObuParser(const uint8_t * const data,size_t size,int operating_point,BufferPool * const buffer_pool,DecoderState * const decoder_state)224 ObuParser(const uint8_t* const data, size_t size, int operating_point, 225 BufferPool* const buffer_pool, DecoderState* const decoder_state) 226 : data_(data), 227 size_(size), 228 operating_point_(operating_point), 229 buffer_pool_(buffer_pool), 230 decoder_state_(*decoder_state) {} 231 232 // Not copyable or movable. 233 ObuParser(const ObuParser& rhs) = delete; 234 ObuParser& operator=(const ObuParser& rhs) = delete; 235 236 // Returns true if there is more data that needs to be parsed. 237 bool HasData() const; 238 239 // Parses a sequence of Open Bitstream Units until a decodable frame is found 240 // (or until the end of stream is reached). A decodable frame is considered to 241 // be found when one of the following happens: 242 // * A kObuFrame is seen. 243 // * The kObuTileGroup containing the last tile is seen. 244 // * A kFrameHeader with show_existing_frame = true is seen. 245 // 246 // If the parsing is successful, relevant fields will be populated. The fields 247 // are valid only if the return value is kStatusOk. Returns kStatusOk on 248 // success, an error status otherwise. On success, |current_frame| will be 249 // populated with a valid frame buffer. 250 StatusCode ParseOneFrame(RefCountedBufferPtr* current_frame); 251 252 // Get the AV1CodecConfigurationBox as described in 253 // https://aomediacodec.github.io/av1-isobmff/#av1codecconfigurationbox. This 254 // does minimal bitstream parsing to obtain the necessary information to 255 // generate the av1c box. Returns a std::unique_ptr that contains the av1c 256 // data on success, nullptr otherwise. |av1c_size| must not be nullptr and 257 // will contain the size of the buffer pointed to by the std::unique_ptr. 258 static std::unique_ptr<uint8_t[]> GetAV1CodecConfigurationBox( 259 const uint8_t* data, size_t size, size_t* av1c_size); 260 261 // Getters. Only valid if ParseOneFrame() completes successfully. obu_headers()262 const Vector<ObuHeader>& obu_headers() const { return obu_headers_; } sequence_header()263 const ObuSequenceHeader& sequence_header() const { return sequence_header_; } frame_header()264 const ObuFrameHeader& frame_header() const { return frame_header_; } tile_buffers()265 const Vector<TileBuffer>& tile_buffers() const { return tile_buffers_; } 266 // Returns true if the last call to ParseOneFrame() encountered a sequence 267 // header change. sequence_header_changed()268 bool sequence_header_changed() const { return sequence_header_changed_; } 269 270 // Setters. set_sequence_header(const ObuSequenceHeader & sequence_header)271 void set_sequence_header(const ObuSequenceHeader& sequence_header) { 272 sequence_header_ = sequence_header; 273 has_sequence_header_ = true; 274 } 275 276 // Moves |tile_buffers_| into |tile_buffers|. MoveTileBuffers(Vector<TileBuffer> * tile_buffers)277 void MoveTileBuffers(Vector<TileBuffer>* tile_buffers) { 278 *tile_buffers = std::move(tile_buffers_); 279 } 280 281 private: 282 // Initializes the bit reader. This is a function of its own to make unit 283 // testing of private functions simpler. 284 LIBGAV1_MUST_USE_RESULT bool InitBitReader(const uint8_t* data, size_t size); 285 286 // Parse helper functions. 287 bool ParseHeader(); // 5.3.2 and 5.3.3. 288 bool ParseColorConfig(ObuSequenceHeader* sequence_header); // 5.5.2. 289 bool ParseTimingInfo(ObuSequenceHeader* sequence_header); // 5.5.3. 290 bool ParseDecoderModelInfo(ObuSequenceHeader* sequence_header); // 5.5.4. 291 bool ParseOperatingParameters(ObuSequenceHeader* sequence_header, 292 int index); // 5.5.5. 293 bool ParseSequenceHeader(bool seen_frame_header); // 5.5.1. 294 bool ParseFrameParameters(); // 5.9.2, 5.9.7 and 5.9.10. 295 void MarkInvalidReferenceFrames(); // 5.9.4. 296 bool ParseFrameSizeAndRenderSize(); // 5.9.5 and 5.9.6. 297 bool ParseSuperResParametersAndComputeImageSize(); // 5.9.8 and 5.9.9. 298 // Checks the bitstream conformance requirement in Section 6.8.6. 299 bool ValidateInterFrameSize() const; 300 bool ParseReferenceOrderHint(); 301 static int FindLatestBackwardReference( 302 const int current_frame_hint, 303 const std::array<int, kNumReferenceFrameTypes>& shifted_order_hints, 304 const std::array<bool, kNumReferenceFrameTypes>& used_frame); 305 static int FindEarliestBackwardReference( 306 const int current_frame_hint, 307 const std::array<int, kNumReferenceFrameTypes>& shifted_order_hints, 308 const std::array<bool, kNumReferenceFrameTypes>& used_frame); 309 static int FindLatestForwardReference( 310 const int current_frame_hint, 311 const std::array<int, kNumReferenceFrameTypes>& shifted_order_hints, 312 const std::array<bool, kNumReferenceFrameTypes>& used_frame); 313 static int FindReferenceWithSmallestOutputOrder( 314 const std::array<int, kNumReferenceFrameTypes>& shifted_order_hints); 315 bool SetFrameReferences(int8_t last_frame_idx, 316 int8_t gold_frame_idx); // 7.8. 317 bool ParseLoopFilterParameters(); // 5.9.11. 318 bool ParseDeltaQuantizer(int8_t* delta); // 5.9.13. 319 bool ParseQuantizerParameters(); // 5.9.12. 320 bool ParseSegmentationParameters(); // 5.9.14. 321 bool ParseQuantizerIndexDeltaParameters(); // 5.9.17. 322 bool ParseLoopFilterDeltaParameters(); // 5.9.18. 323 void ComputeSegmentLosslessAndQIndex(); 324 bool ParseCdefParameters(); // 5.9.19. 325 bool ParseLoopRestorationParameters(); // 5.9.20. 326 bool ParseTxModeSyntax(); // 5.9.21. 327 bool ParseFrameReferenceModeSyntax(); // 5.9.23. 328 // Returns whether skip mode is allowed. When it returns true, it also sets 329 // the frame_header_.skip_mode_frame array. 330 bool IsSkipModeAllowed(); 331 bool ParseSkipModeParameters(); // 5.9.22. 332 bool ReadAllowWarpedMotion(); 333 bool ParseGlobalParamSyntax( 334 int ref, int index, 335 const std::array<GlobalMotion, kNumReferenceFrameTypes>& 336 prev_global_motions); // 5.9.25. 337 bool ParseGlobalMotionParameters(); // 5.9.24. 338 bool ParseFilmGrainParameters(); // 5.9.30. 339 bool ParseTileInfoSyntax(); // 5.9.15. 340 bool ParseFrameHeader(); // 5.9. 341 // |data| and |size| specify the payload data of the padding OBU. 342 // NOTE: Although the payload data is available in the bit_reader_ member, 343 // it is also passed to ParsePadding() as function parameters so that 344 // ParsePadding() can find the trailing bit of the OBU and skip over the 345 // payload data as an opaque chunk of data. 346 bool ParsePadding(const uint8_t* data, size_t size); // 5.7. 347 bool ParseMetadataScalability(); // 5.8.5 and 5.8.6. 348 bool ParseMetadataTimecode(); // 5.8.7. 349 // |data| and |size| specify the payload data of the metadata OBU. 350 // NOTE: Although the payload data is available in the bit_reader_ member, 351 // it is also passed to ParseMetadata() as function parameters so that 352 // ParseMetadata() can find the trailing bit of the OBU and either extract 353 // or skip over the payload data as an opaque chunk of data. 354 bool ParseMetadata(const uint8_t* data, size_t size); // 5.8. 355 // Adds and populates the TileBuffer for each tile in the tile group and 356 // updates |next_tile_group_start_| 357 bool AddTileBuffers(int start, int end, size_t total_size, 358 size_t tg_header_size, size_t bytes_consumed_so_far); 359 bool ParseTileGroup(size_t size, size_t bytes_consumed_so_far); // 5.11.1. 360 361 // Populates |current_frame_| from the |buffer_pool_| if |current_frame_| is 362 // nullptr. Does not do anything otherwise. Returns true on success, false 363 // otherwise. 364 bool EnsureCurrentFrameIsNotNull(); 365 366 // Parses the basic bitstream information from the given AV1 stream in |data|. 367 // This is used for generating the AV1CodecConfigurationBox. 368 static StatusCode ParseBasicStreamInfo(const uint8_t* data, size_t size, 369 ObuSequenceHeader* sequence_header, 370 size_t* sequence_header_offset, 371 size_t* sequence_header_size); 372 373 // Parser elements. 374 std::unique_ptr<RawBitReader> bit_reader_; 375 const uint8_t* data_; 376 size_t size_; 377 const int operating_point_; 378 379 // OBU elements. Only valid if ParseOneFrame() completes successfully. 380 Vector<ObuHeader> obu_headers_; 381 ObuSequenceHeader sequence_header_ = {}; 382 ObuFrameHeader frame_header_ = {}; 383 Vector<TileBuffer> tile_buffers_; 384 // The expected starting tile number of the next Tile Group. 385 int next_tile_group_start_ = 0; 386 // If true, the sequence_header_ field is valid. 387 bool has_sequence_header_ = false; 388 // If true, it means that the last call to ParseOneFrame() encountered a 389 // sequence header change. 390 bool sequence_header_changed_ = false; 391 // If true, the obu_extension_flag syntax element in the OBU header must be 392 // 0. Set to true when parsing a sequence header if OperatingPointIdc is 0. 393 bool extension_disallowed_ = false; 394 395 BufferPool* const buffer_pool_; 396 DecoderState& decoder_state_; 397 // Used by ParseOneFrame() to populate the current frame that is being 398 // decoded. The invariant maintained is that this variable will be nullptr at 399 // the beginning and at the end of each call to ParseOneFrame(). This ensures 400 // that the ObuParser is not holding on to any references to the current 401 // frame once the ParseOneFrame() call is complete. 402 RefCountedBufferPtr current_frame_; 403 404 // For unit testing private functions. 405 friend class ObuParserTest; 406 }; 407 408 } // namespace libgav1 409 410 #endif // LIBGAV1_SRC_OBU_PARSER_H_ 411