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
23struct vpx_codec_ctx;
24struct vpx_codec_frame_buffer;
25
26namespace 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);
54class 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