Home | History | Annotate | Download | only in vp9 
      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 WEBRTC_MODULES_VIDEO_CODING_CODECS_VP9_FRAME_BUFFER_POOL_H_
     13 #define WEBRTC_MODULES_VIDEO_CODING_CODECS_VP9_FRAME_BUFFER_POOL_H_
     14 
     15 #include <vector>
     16 
     17 #include "webrtc/base/basictypes.h"
     18 #include "webrtc/base/buffer.h"
     19 #include "webrtc/base/criticalsection.h"
     20 #include "webrtc/base/refcount.h"
     21 #include "webrtc/base/scoped_ref_ptr.h"
     22 
     23 struct vpx_codec_ctx;
     24 struct vpx_codec_frame_buffer;
     25 
     26 namespace webrtc {
     27 
     28 // This memory pool is used to serve buffers to libvpx for decoding purposes in
     29 // VP9, which is set up in InitializeVPXUsePool. After the initialization any
     30 // time libvpx wants to decode a frame it will use buffers provided and released
     31 // through VpxGetFrameBuffer and VpxReleaseFrameBuffer.
     32 // The benefit of owning the pool that libvpx relies on for decoding is that the
     33 // decoded frames returned by libvpx (from vpx_codec_get_frame) use parts of our
     34 // buffers for the decoded image data. By retaining ownership of this buffer
     35 // using scoped_refptr, the image buffer can be reused by VideoFrames and no
     36 // frame copy has to occur during decoding and frame delivery.
     37 //
     38 // Pseudo example usage case:
     39 //    Vp9FrameBufferPool pool;
     40 //    pool.InitializeVpxUsePool(decoder_ctx);
     41 //    ...
     42 //
     43 //    // During decoding, libvpx will get and release buffers from the pool.
     44 //    vpx_codec_decode(decoder_ctx, ...);
     45 //
     46 //    vpx_image_t* img = vpx_codec_get_frame(decoder_ctx, &iter);
     47 //    // Important to use scoped_refptr to protect it against being recycled by
     48 //    // the pool.
     49 //    scoped_refptr<Vp9FrameBuffer> img_buffer = (Vp9FrameBuffer*)img->fb_priv;
     50 //    ...
     51 //
     52 //    // Destroying the codec will make libvpx release any buffers it was using.
     53 //    vpx_codec_destroy(decoder_ctx);
     54 class Vp9FrameBufferPool {
     55  public:
     56   class Vp9FrameBuffer : public rtc::RefCountInterface {
     57    public:
     58     uint8_t* GetData();
     59     size_t GetDataSize() const;
     60     void SetSize(size_t size);
     61 
     62     virtual bool HasOneRef() const = 0;
     63 
     64    private:
     65     // Data as an easily resizable buffer.
     66     rtc::Buffer data_;
     67   };
     68 
     69   // Configures libvpx to, in the specified context, use this memory pool for
     70   // buffers used to decompress frames. This is only supported for VP9.
     71   bool InitializeVpxUsePool(vpx_codec_ctx* vpx_codec_context);
     72 
     73   // Gets a frame buffer of at least |min_size|, recycling an available one or
     74   // creating a new one. When no longer referenced from the outside the buffer
     75   // becomes recyclable.
     76   rtc::scoped_refptr<Vp9FrameBuffer> GetFrameBuffer(size_t min_size);
     77   // Gets the number of buffers currently in use (not ready to be recycled).
     78   int GetNumBuffersInUse() const;
     79   // Releases allocated buffers, deleting available buffers. Buffers in use are
     80   // not deleted until they are no longer referenced.
     81   void ClearPool();
     82 
     83   // InitializeVpxUsePool configures libvpx to call this function when it needs
     84   // a new frame buffer. Parameters:
     85   // |user_priv| Private data passed to libvpx, InitializeVpxUsePool sets it up
     86   //             to be a pointer to the pool.
     87   // |min_size|  Minimum size needed by libvpx (to decompress a frame).
     88   // |fb|        Pointer to the libvpx frame buffer object, this is updated to
     89   //             use the pool's buffer.
     90   // Returns 0 on success. Returns < 0 on failure.
     91   static int32_t VpxGetFrameBuffer(void* user_priv,
     92                                    size_t min_size,
     93                                    vpx_codec_frame_buffer* fb);
     94 
     95   // InitializeVpxUsePool configures libvpx to call this function when it has
     96   // finished using one of the pool's frame buffer. Parameters:
     97   // |user_priv| Private data passed to libvpx, InitializeVpxUsePool sets it up
     98   //             to be a pointer to the pool.
     99   // |fb|        Pointer to the libvpx frame buffer object, its |priv| will be
    100   //             a pointer to one of the pool's Vp9FrameBuffer.
    101   static int32_t VpxReleaseFrameBuffer(void* user_priv,
    102                                        vpx_codec_frame_buffer* fb);
    103 
    104  private:
    105   // Protects |allocated_buffers_|.
    106   mutable rtc::CriticalSection buffers_lock_;
    107   // All buffers, in use or ready to be recycled.
    108   std::vector<rtc::scoped_refptr<Vp9FrameBuffer>> allocated_buffers_
    109       GUARDED_BY(buffers_lock_);
    110   // If more buffers than this are allocated we print warnings, and crash if
    111   // in debug mode.
    112   static const size_t max_num_buffers_ = 10;
    113 };
    114 
    115 }  // namespace webrtc
    116 
    117 #endif  // WEBRTC_MODULES_VIDEO_CODING_CODECS_VP9_FRAME_BUFFER_POOL_H_
    118