1 /*
2 * Copyright 2020 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_FRAME_BUFFER_H_
18 #define LIBGAV1_SRC_GAV1_FRAME_BUFFER_H_
19
20 // All the declarations in this file are part of the public ABI. This file may
21 // be included by both C and C++ files.
22
23 #if defined(__cplusplus)
24 #include <cstddef>
25 #include <cstdint>
26 #else
27 #include <stddef.h>
28 #include <stdint.h>
29 #endif // defined(__cplusplus)
30
31 #include "gav1/decoder_buffer.h"
32 #include "gav1/status_code.h"
33 #include "gav1/symbol_visibility.h"
34
35 // The callback functions use the C linkage conventions.
36 #if defined(__cplusplus)
37 extern "C" {
38 #endif
39
40 // This structure represents an allocated frame buffer.
41 typedef struct Libgav1FrameBuffer {
42 // In the |plane| and |stride| arrays, the elements at indexes 0, 1, and 2
43 // are for the Y, U, and V planes, respectively.
44 uint8_t* plane[3]; // Pointers to the frame (excluding the borders) in the
45 // data buffers.
46 int stride[3]; // Row strides in bytes.
47 void* private_data; // Frame buffer's private data. Available for use by the
48 // release frame buffer callback. Also copied to the
49 // |buffer_private_data| field of DecoderBuffer for use
50 // by the consumer of a DecoderBuffer.
51 } Libgav1FrameBuffer;
52
53 // This callback is invoked by the decoder to provide information on the
54 // subsequent frames in the video, until the next invocation of this callback
55 // or the end of the video.
56 //
57 // |width| and |height| are the maximum frame width and height in pixels.
58 // |left_border|, |right_border|, |top_border|, and |bottom_border| are the
59 // maximum left, right, top, and bottom border sizes in pixels.
60 // |stride_alignment| specifies the alignment of the row stride in bytes.
61 //
62 // Returns kLibgav1StatusOk on success, an error status on failure.
63 //
64 // NOTE: This callback may be omitted if the information is not useful to the
65 // application.
66 typedef Libgav1StatusCode (*Libgav1FrameBufferSizeChangedCallback)(
67 void* callback_private_data, int bitdepth, Libgav1ImageFormat image_format,
68 int width, int height, int left_border, int right_border, int top_border,
69 int bottom_border, int stride_alignment);
70
71 // This callback is invoked by the decoder to allocate a frame buffer, which
72 // consists of three data buffers, for the Y, U, and V planes, respectively.
73 //
74 // The callback must set |frame_buffer->plane[i]| to point to the data buffers
75 // of the planes, and set |frame_buffer->stride[i]| to the row strides of the
76 // planes. If |image_format| is kLibgav1ImageFormatMonochrome400, the callback
77 // should set |frame_buffer->plane[1]| and |frame_buffer->plane[2]| to a null
78 // pointer and set |frame_buffer->stride[1]| and |frame_buffer->stride[2]| to
79 // 0. The callback may set |frame_buffer->private_data| to a value that will
80 // be useful to the release frame buffer callback and the consumer of a
81 // DecoderBuffer.
82 //
83 // Returns kLibgav1StatusOk on success, an error status on failure.
84
85 // |width| and |height| are the frame width and height in pixels.
86 // |left_border|, |right_border|, |top_border|, and |bottom_border| are the
87 // left, right, top, and bottom border sizes in pixels. |stride_alignment|
88 // specifies the alignment of the row stride in bytes.
89 typedef Libgav1StatusCode (*Libgav1GetFrameBufferCallback)(
90 void* callback_private_data, int bitdepth, Libgav1ImageFormat image_format,
91 int width, int height, int left_border, int right_border, int top_border,
92 int bottom_border, int stride_alignment, Libgav1FrameBuffer* frame_buffer);
93
94 // After a frame buffer is allocated, the decoder starts to write decoded video
95 // to the frame buffer. When the frame buffer is ready for consumption, it is
96 // made available to the application in a Decoder::DequeueFrame() call.
97 // Afterwards, the decoder may continue to use the frame buffer in read-only
98 // mode. When the decoder is finished using the frame buffer, it notifies the
99 // application by calling the Libgav1ReleaseFrameBufferCallback.
100
101 // This callback is invoked by the decoder to release a frame buffer.
102 typedef void (*Libgav1ReleaseFrameBufferCallback)(void* callback_private_data,
103 void* buffer_private_data);
104
105 // Libgav1ComputeFrameBufferInfo() and Libgav1SetFrameBuffer() are intended to
106 // help clients implement frame buffer callbacks using memory buffers. First,
107 // call Libgav1ComputeFrameBufferInfo(). If it succeeds, allocate y_buffer of
108 // size info.y_buffer_size and allocate u_buffer and v_buffer, both of size
109 // info.uv_buffer_size. Finally, pass y_buffer, u_buffer, v_buffer, and
110 // buffer_private_data to Libgav1SetFrameBuffer().
111
112 // This structure contains information useful for allocating memory for a frame
113 // buffer.
114 typedef struct Libgav1FrameBufferInfo {
115 size_t y_buffer_size; // Size in bytes of the Y buffer.
116 size_t uv_buffer_size; // Size in bytes of the U or V buffer.
117
118 // The following fields are consumed by Libgav1SetFrameBuffer(). Do not use
119 // them directly.
120 int y_stride; // Row stride in bytes of the Y buffer.
121 int uv_stride; // Row stride in bytes of the U or V buffer.
122 size_t y_plane_offset; // Offset in bytes of the frame (excluding the
123 // borders) in the Y buffer.
124 size_t uv_plane_offset; // Offset in bytes of the frame (excluding the
125 // borders) in the U or V buffer.
126 int stride_alignment; // The stride_alignment argument passed to
127 // Libgav1ComputeFrameBufferInfo().
128 } Libgav1FrameBufferInfo;
129
130 // Computes the information useful for allocating memory for a frame buffer.
131 // On success, stores the output in |info|.
132 LIBGAV1_PUBLIC Libgav1StatusCode Libgav1ComputeFrameBufferInfo(
133 int bitdepth, Libgav1ImageFormat image_format, int width, int height,
134 int left_border, int right_border, int top_border, int bottom_border,
135 int stride_alignment, Libgav1FrameBufferInfo* info);
136
137 // Sets the |frame_buffer| struct.
138 LIBGAV1_PUBLIC Libgav1StatusCode Libgav1SetFrameBuffer(
139 const Libgav1FrameBufferInfo* info, uint8_t* y_buffer, uint8_t* u_buffer,
140 uint8_t* v_buffer, void* buffer_private_data,
141 Libgav1FrameBuffer* frame_buffer);
142
143 #if defined(__cplusplus)
144 } // extern "C"
145
146 // Declare type aliases for C++.
147 namespace libgav1 {
148
149 using FrameBuffer = Libgav1FrameBuffer;
150 using FrameBufferSizeChangedCallback = Libgav1FrameBufferSizeChangedCallback;
151 using GetFrameBufferCallback = Libgav1GetFrameBufferCallback;
152 using ReleaseFrameBufferCallback = Libgav1ReleaseFrameBufferCallback;
153 using FrameBufferInfo = Libgav1FrameBufferInfo;
154
ComputeFrameBufferInfo(int bitdepth,ImageFormat image_format,int width,int height,int left_border,int right_border,int top_border,int bottom_border,int stride_alignment,FrameBufferInfo * info)155 inline StatusCode ComputeFrameBufferInfo(int bitdepth, ImageFormat image_format,
156 int width, int height, int left_border,
157 int right_border, int top_border,
158 int bottom_border,
159 int stride_alignment,
160 FrameBufferInfo* info) {
161 return Libgav1ComputeFrameBufferInfo(bitdepth, image_format, width, height,
162 left_border, right_border, top_border,
163 bottom_border, stride_alignment, info);
164 }
165
SetFrameBuffer(const FrameBufferInfo * info,uint8_t * y_buffer,uint8_t * u_buffer,uint8_t * v_buffer,void * buffer_private_data,FrameBuffer * frame_buffer)166 inline StatusCode SetFrameBuffer(const FrameBufferInfo* info, uint8_t* y_buffer,
167 uint8_t* u_buffer, uint8_t* v_buffer,
168 void* buffer_private_data,
169 FrameBuffer* frame_buffer) {
170 return Libgav1SetFrameBuffer(info, y_buffer, u_buffer, v_buffer,
171 buffer_private_data, frame_buffer);
172 }
173
174 } // namespace libgav1
175 #endif // defined(__cplusplus)
176
177 #endif // LIBGAV1_SRC_GAV1_FRAME_BUFFER_H_
178