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_GAV1_DECODER_H_ 18 #define LIBGAV1_SRC_GAV1_DECODER_H_ 19 20 #if defined(__cplusplus) 21 #include <cstddef> 22 #include <cstdint> 23 #include <memory> 24 #include <vector> 25 #else 26 #include <stddef.h> 27 #include <stdint.h> 28 #endif // defined(__cplusplus) 29 30 // IWYU pragma: begin_exports 31 #include "gav1/decoder_buffer.h" 32 #include "gav1/decoder_settings.h" 33 #include "gav1/frame_buffer.h" 34 #include "gav1/status_code.h" 35 #include "gav1/symbol_visibility.h" 36 #include "gav1/version.h" 37 // IWYU pragma: end_exports 38 39 #if defined(__cplusplus) 40 extern "C" { 41 #endif 42 43 struct Libgav1Decoder; 44 typedef struct Libgav1Decoder Libgav1Decoder; 45 46 LIBGAV1_PUBLIC Libgav1StatusCode Libgav1DecoderCreate( 47 const Libgav1DecoderSettings* settings, Libgav1Decoder** decoder_out); 48 49 LIBGAV1_PUBLIC void Libgav1DecoderDestroy(Libgav1Decoder* decoder); 50 51 LIBGAV1_PUBLIC Libgav1StatusCode Libgav1DecoderEnqueueFrame( 52 Libgav1Decoder* decoder, const uint8_t* data, size_t size, 53 int64_t user_private_data, void* buffer_private_data); 54 55 LIBGAV1_PUBLIC Libgav1StatusCode Libgav1DecoderDequeueFrame( 56 Libgav1Decoder* decoder, const Libgav1DecoderBuffer** out_ptr); 57 58 LIBGAV1_PUBLIC Libgav1StatusCode 59 Libgav1DecoderSignalEOS(Libgav1Decoder* decoder); 60 61 LIBGAV1_PUBLIC int Libgav1DecoderGetMaxBitdepth(void); 62 63 #if defined(__cplusplus) 64 } // extern "C" 65 66 namespace libgav1 { 67 68 // Forward declaration. 69 class DecoderImpl; 70 71 class LIBGAV1_PUBLIC Decoder { 72 public: 73 Decoder(); 74 ~Decoder(); 75 76 // Init must be called exactly once per instance. Subsequent calls will do 77 // nothing. If |settings| is nullptr, the decoder will be initialized with 78 // default settings. Returns kStatusOk on success, an error status otherwise. 79 StatusCode Init(const DecoderSettings* settings); 80 81 // Enqueues a compressed frame to be decoded. 82 // 83 // This function returns: 84 // * kStatusOk on success 85 // * kStatusTryAgain if the decoder queue is full 86 // * an error status otherwise. 87 // 88 // |user_private_data| may be used to associate application specific private 89 // data with the compressed frame. It will be copied to the user_private_data 90 // field of the DecoderBuffer returned by the corresponding |DequeueFrame()| 91 // call. 92 // 93 // NOTE: |EnqueueFrame()| does not copy the data. Therefore, after a 94 // successful |EnqueueFrame()| call, the caller must keep the |data| buffer 95 // alive until: 96 // 1) If |settings_.release_input_buffer| is not nullptr, then |data| buffer 97 // must be kept alive until release_input_buffer is called with the 98 // |buffer_private_data| passed into this EnqueueFrame call. 99 // 2) If |settings_.release_input_buffer| is nullptr, then |data| buffer must 100 // be kept alive until the corresponding DequeueFrame() call is completed. 101 // 102 // If the call to |EnqueueFrame()| is not successful, then libgav1 will not 103 // hold any references to the |data| buffer. |settings_.release_input_buffer| 104 // callback will not be called in that case. 105 StatusCode EnqueueFrame(const uint8_t* data, size_t size, 106 int64_t user_private_data, void* buffer_private_data); 107 108 // Dequeues a decompressed frame. If there are enqueued compressed frames, 109 // decodes one and sets |*out_ptr| to the last displayable frame in the 110 // compressed frame. If there are no displayable frames available, sets 111 // |*out_ptr| to nullptr. 112 // 113 // Returns kStatusOk on success. Returns kStatusNothingToDequeue if there are 114 // no enqueued frames (in this case out_ptr will always be set to nullptr). 115 // Returns one of the other error statuses if there is an error. 116 // 117 // If |settings_.blocking_dequeue| is false and the decoder is operating in 118 // frame parallel mode (|settings_.frame_parallel| is true and the video 119 // stream passes the decoder's heuristics for enabling frame parallel mode), 120 // then this call will return kStatusTryAgain if an enqueued frame is not yet 121 // decoded (it is a non blocking call in this case). In all other cases, this 122 // call will block until an enqueued frame has been decoded. 123 StatusCode DequeueFrame(const DecoderBuffer** out_ptr); 124 125 // Signals the end of stream. 126 // 127 // In non-frame-parallel mode, this function will release all the frames held 128 // by the decoder. If the frame buffers were allocated by libgav1, then the 129 // pointer obtained by the prior DequeueFrame call will no longer be valid. If 130 // the frame buffers were allocated by the application, then any references 131 // that libgav1 is holding on to will be released. 132 // 133 // Once this function returns successfully, the decoder state will be reset 134 // and the decoder is ready to start decoding a new coded video sequence. 135 StatusCode SignalEOS(); 136 137 // Returns the maximum bitdepth that is supported by this decoder. 138 static int GetMaxBitdepth(); 139 140 // Returns a vector with the QP values for all the frames in the last temporal 141 // unit in encoding/decoding order (Note: not display order). If no frames are 142 // present in the last temporal unit the method returns an empty vector. 143 // 144 // NOTE: This function is C++ only and is not exposed via the C API. 145 // 146 // TODO(vardar): return a map that contains a QP per spatial layer for each 147 // temporal layer. 148 std::vector<int> GetFramesMeanQpInTemporalUnit(); 149 150 private: 151 DecoderSettings settings_; 152 // The object is initialized if and only if impl_ != nullptr. 153 std::unique_ptr<DecoderImpl> impl_; 154 std::vector<int> frame_mean_qps_; 155 }; 156 157 } // namespace libgav1 158 #endif // defined(__cplusplus) 159 160 #endif // LIBGAV1_SRC_GAV1_DECODER_H_ 161