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