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