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