1 /* 2 * Copyright (c) 2015 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 * 10 */ 11 12 #ifndef MODULES_VIDEO_CODING_CODECS_VP9_VP9_FRAME_BUFFER_POOL_H_ 13 #define MODULES_VIDEO_CODING_CODECS_VP9_VP9_FRAME_BUFFER_POOL_H_ 14 15 #ifdef RTC_ENABLE_VP9 16 17 #include <vector> 18 19 #include "api/ref_counted_base.h" 20 #include "api/scoped_refptr.h" 21 #include "rtc_base/buffer.h" 22 #include "rtc_base/synchronization/mutex.h" 23 24 struct vpx_codec_ctx; 25 struct vpx_codec_frame_buffer; 26 27 namespace webrtc { 28 29 // If more buffers than this are allocated we print warnings and crash if in 30 // debug mode. VP9 is defined to have 8 reference buffers, of which 3 can be 31 // referenced by any frame, see 32 // https://tools.ietf.org/html/draft-grange-vp9-bitstream-00#section-2.2.2. 33 // Assuming VP9 holds on to at most 8 buffers, any more buffers than that 34 // would have to be by application code. Decoded frames should not be 35 // referenced for longer than necessary. If we allow ~60 additional buffers 36 // then the application has ~1 second to e.g. render each frame of a 60 fps 37 // video. 38 constexpr size_t kDefaultMaxNumBuffers = 68; 39 40 // This memory pool is used to serve buffers to libvpx for decoding purposes in 41 // VP9, which is set up in InitializeVPXUsePool. After the initialization any 42 // time libvpx wants to decode a frame it will use buffers provided and released 43 // through VpxGetFrameBuffer and VpxReleaseFrameBuffer. 44 // The benefit of owning the pool that libvpx relies on for decoding is that the 45 // decoded frames returned by libvpx (from vpx_codec_get_frame) use parts of our 46 // buffers for the decoded image data. By retaining ownership of this buffer 47 // using scoped_refptr, the image buffer can be reused by VideoFrames and no 48 // frame copy has to occur during decoding and frame delivery. 49 // 50 // Pseudo example usage case: 51 // Vp9FrameBufferPool pool; 52 // pool.InitializeVpxUsePool(decoder_ctx); 53 // ... 54 // 55 // // During decoding, libvpx will get and release buffers from the pool. 56 // vpx_codec_decode(decoder_ctx, ...); 57 // 58 // vpx_image_t* img = vpx_codec_get_frame(decoder_ctx, &iter); 59 // // Important to use scoped_refptr to protect it against being recycled by 60 // // the pool. 61 // scoped_refptr<Vp9FrameBuffer> img_buffer = (Vp9FrameBuffer*)img->fb_priv; 62 // ... 63 // 64 // // Destroying the codec will make libvpx release any buffers it was using. 65 // vpx_codec_destroy(decoder_ctx); 66 class Vp9FrameBufferPool { 67 public: 68 class Vp9FrameBuffer final 69 : public rtc::RefCountedNonVirtual<Vp9FrameBuffer> { 70 public: 71 uint8_t* GetData(); 72 size_t GetDataSize() const; 73 void SetSize(size_t size); 74 75 using rtc::RefCountedNonVirtual<Vp9FrameBuffer>::HasOneRef; 76 77 private: 78 // Data as an easily resizable buffer. 79 rtc::Buffer data_; 80 }; 81 82 // Configures libvpx to, in the specified context, use this memory pool for 83 // buffers used to decompress frames. This is only supported for VP9. 84 bool InitializeVpxUsePool(vpx_codec_ctx* vpx_codec_context); 85 86 // Gets a frame buffer of at least `min_size`, recycling an available one or 87 // creating a new one. When no longer referenced from the outside the buffer 88 // becomes recyclable. 89 rtc::scoped_refptr<Vp9FrameBuffer> GetFrameBuffer(size_t min_size); 90 // Gets the number of buffers currently in use (not ready to be recycled). 91 int GetNumBuffersInUse() const; 92 // Changes the max amount of buffers in the pool to the new value. 93 // Returns true if change was successful and false if the amount of already 94 // allocated buffers is bigger than new value. 95 bool Resize(size_t max_number_of_buffers); 96 // Releases allocated buffers, deleting available buffers. Buffers in use are 97 // not deleted until they are no longer referenced. 98 void ClearPool(); 99 100 // InitializeVpxUsePool configures libvpx to call this function when it needs 101 // a new frame buffer. Parameters: 102 // `user_priv` Private data passed to libvpx, InitializeVpxUsePool sets it up 103 // to be a pointer to the pool. 104 // `min_size` Minimum size needed by libvpx (to decompress a frame). 105 // `fb` Pointer to the libvpx frame buffer object, this is updated to 106 // use the pool's buffer. 107 // Returns 0 on success. Returns < 0 on failure. 108 static int32_t VpxGetFrameBuffer(void* user_priv, 109 size_t min_size, 110 vpx_codec_frame_buffer* fb); 111 112 // InitializeVpxUsePool configures libvpx to call this function when it has 113 // finished using one of the pool's frame buffer. Parameters: 114 // `user_priv` Private data passed to libvpx, InitializeVpxUsePool sets it up 115 // to be a pointer to the pool. 116 // `fb` Pointer to the libvpx frame buffer object, its `priv` will be 117 // a pointer to one of the pool's Vp9FrameBuffer. 118 static int32_t VpxReleaseFrameBuffer(void* user_priv, 119 vpx_codec_frame_buffer* fb); 120 121 private: 122 // Protects `allocated_buffers_`. 123 mutable Mutex buffers_lock_; 124 // All buffers, in use or ready to be recycled. 125 std::vector<rtc::scoped_refptr<Vp9FrameBuffer>> allocated_buffers_ 126 RTC_GUARDED_BY(buffers_lock_); 127 size_t max_num_buffers_ = kDefaultMaxNumBuffers; 128 }; 129 130 } // namespace webrtc 131 132 #endif // RTC_ENABLE_VP9 133 134 #endif // MODULES_VIDEO_CODING_CODECS_VP9_VP9_FRAME_BUFFER_POOL_H_ 135