bitwriter: add comments of each interfaces
[vaapi:windyuan-gstreamer-vaapi.git] / gst-libs / gst / bitwriter / gstbitwriter.c
1 /*
2  *  gstbitwriter.c - bitstream writer
3  *
4  *  Copyright (C) 2013 Intel Corporation
5  *
6  *  This library is free software; you can redistribute it and/or
7  *  modify it under the terms of the GNU Lesser General Public License
8  *  as published by the Free Software Foundation; either version 2.1
9  *  of the License, or (at your option) any later version.
10  *
11  *  This library is distributed in the hope that it will be useful,
12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  *  Lesser General Public License for more details.
15  *
16  *  You should have received a copy of the GNU Lesser General Public
17  *  License along with this library; if not, write to the Free
18  *  Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19  *  Boston, MA 02110-1301 USA
20  */
21
22 #define GST_BIT_WRITER_DISABLE_INLINES
23
24 #include "gstbitwriter.h"
25
26 /**
27  * gst_bit_writer_init:
28  * @bitwriter: a #GstBitWriter instance
29  * @reserved_bits: reserved bits to allocate data
30  *
31  * Initializes a #GstBitWriter instance and allocate @reserved_bits data inside.
32  *
33  * Cleanup function: gst_bit_writer_clear
34  */
35 void
36 gst_bit_writer_init(GstBitWriter *bitwriter, guint32 reserved_bits)
37 {
38     bitwriter->bit_size = 0;
39     bitwriter->data = NULL;
40     bitwriter->bit_capacity = 0;
41     bitwriter->auto_grow = TRUE;
42     if (reserved_bits)
43         _gst_bit_writer_check_space(bitwriter, reserved_bits);
44 }
45
46 /**
47  * gst_bit_writer_init_fill:
48  * @bitwriter: a #GstBitWriter instance
49  * @data: allocated data
50   * @bits: size of allocated @data in bits
51  *
52  * Initializes a #GstBitWriter instance with alocated @data and @bit outside.
53  *
54  * Cleanup function: gst_bit_writer_clear
55  */
56 void
57 gst_bit_writer_init_fill(GstBitWriter *bitwriter, guint8 *data, guint bits)
58 {
59     bitwriter->bit_size = 0;
60     bitwriter->data = data;
61     bitwriter->bit_capacity = bits;
62     bitwriter->auto_grow = FALSE;
63 }
64
65 /**
66  * gst_bit_writer_clear:
67  * @bitwriter: a #GstBitWriter instance
68  * @free_data: flag to free #GstBitWriter allocated data
69  *
70  * Clear a #GstBitWriter instance and destroy allocated data inside
71  * if @free_data is %TRUE.
72  */
73 void
74 gst_bit_writer_clear(GstBitWriter *bitwriter, gboolean free_data)
75 {
76     if (bitwriter->auto_grow && bitwriter->data && free_data)
77         g_free (bitwriter->data);
78
79     bitwriter->data = NULL;
80     bitwriter->bit_size = 0;
81     bitwriter->bit_capacity = 0;
82 }
83
84 /**
85  * gst_bit_writer_new:
86  * @bitwriter: a #GstBitWriter instance
87  * @reserved_bits: reserved bits to allocate data
88  *
89  * Create a #GstBitWriter instance and allocate @reserved_bits data inside.
90  *
91  * Free-function: gst_bit_writer_free
92  *
93  * Returns: a new #GstBitWriter instance
94  */
95 GstBitWriter *
96 gst_bit_writer_new(guint32 reserved_bits)
97 {
98     GstBitWriter *ret = g_slice_new0 (GstBitWriter);
99
100     gst_bit_writer_init(ret, reserved_bits);
101
102     return ret;
103 }
104
105 /**
106  * gst_bit_writer_new_fill:
107  * @bitwriter: a #GstBitWriter instance
108  * @data: allocated data
109  * @bits: size of allocated @data in bits
110  *
111  * Create a #GstBitWriter instance with allocated @data and @bit outside.
112  *
113  * Free-function: gst_bit_writer_free
114  *
115  * Returns: a new #GstBitWriter instance
116  */
117 GstBitWriter *
118 gst_bit_writer_new_fill(guint8 *data, guint bits)
119 {
120     GstBitWriter *ret = g_slice_new0 (GstBitWriter);
121
122     gst_bit_writer_init_fill(ret, data, bits);
123
124     return ret;
125 }
126
127
128 /**
129  * gst_bit_writer_free:
130  * @bitwriter: a #GstBitWriter instance
131  * @free_data:  flag to free @data which is allocated inside
132  *
133  * Clear a #GstBitWriter instance and destroy allocated data inside if
134  * @free_data is %TRUE
135  */
136 void
137 gst_bit_writer_free(GstBitWriter *writer, gboolean free_data)
138 {
139     g_return_if_fail (writer != NULL);
140
141     gst_bit_writer_clear(writer, free_data);
142
143     g_slice_free (GstBitWriter, writer);
144 }
145
146 /**
147  * gst_bit_writer_get_size:
148  * @bitwriter: a #GstBitWriter instance
149  *
150  * Get size of written @data
151  *
152  * Returns: size of bits written in @data
153  */
154 guint
155 gst_bit_writer_get_size(GstBitWriter *bitwriter)
156 {
157     return _gst_bit_writer_get_size_inline(bitwriter);
158 }
159
160 /**
161  * gst_bit_writer_get_data:
162  * @bitwriter: a #GstBitWriter instance
163  *
164  * Get written @data pointer
165  *
166  * Returns: @data pointer
167  */
168 guint8 *
169 gst_bit_writer_get_data(GstBitWriter *bitwriter)
170 {
171     return _gst_bit_writer_get_data_inline(bitwriter);
172 }
173
174 /**
175  * gst_bit_writer_get_data:
176  * @bitwriter: a #GstBitWriter instance
177  * @pos: new position of data end
178  *
179  * Set the new postion of data end which should be the new size of @data.
180  *
181  * Returns: %TRUE if successful, %FALSE otherwise
182  */
183 gboolean
184 gst_bit_writer_set_pos(GstBitWriter *bitwriter, guint pos)
185 {
186     return _gst_bit_writer_set_pos_inline(bitwriter, pos);
187 }
188
189 /**
190  * gst_bit_writer_put_bits_uint8:
191  * @bitwriter: a #GstBitWriter instance
192  * @value: value of #guint8 to write
193  * @nbits: number of bits to write
194  *
195  * Write @nbits bits of @value to #GstBitWriter.
196  *
197  * Returns: %TRUE if successful, %FALSE otherwise.
198  */
199
200 /**
201  * gst_bit_writer_put_bits_uint16:
202  * @bitwriter: a #GstBitWriter instance
203  * @value: value of #guint16 to write
204  * @nbits: number of bits to write
205  *
206  * Write @nbits bits of @value to #GstBitWriter.
207  *
208  * Returns: %TRUE if successful, %FALSE otherwise.
209  */
210
211 /**
212  * gst_bit_writer_put_bits_uint32:
213  * @bitwriter: a #GstBitWriter instance
214  * @value: value of #guint32 to write
215  * @nbits: number of bits to write
216  *
217  * Write @nbits bits of @value to #GstBitWriter.
218  *
219  * Returns: %TRUE if successful, %FALSE otherwise.
220  */
221
222 /**
223  * gst_bit_writer_put_bits_uint64:
224  * @bitwriter: a #GstBitWriter instance
225  * @value: value of #guint64 to write
226  * @nbits: number of bits to write
227  *
228  * Write @nbits bits of @value to #GstBitWriter.
229  *
230  * Returns: %TRUE if successful, %FALSE otherwise.
231  */
232
233 #define GST_BIT_WRITER_WRITE_BITS(bits) \
234 gboolean \
235 gst_bit_writer_put_bits_uint##bits (GstBitWriter *bitwriter, guint##bits value, guint nbits) \
236 { \
237   return _gst_bit_writer_put_bits_uint##bits##_inline (bitwriter, value, nbits); \
238 }
239
240 GST_BIT_WRITER_WRITE_BITS(8)
241 GST_BIT_WRITER_WRITE_BITS(16)
242 GST_BIT_WRITER_WRITE_BITS(32)
243 GST_BIT_WRITER_WRITE_BITS(64)
244
245 /**
246  * gst_bit_writer_put_bytes:
247  * @bitwriter: a #GstBitWriter instance
248  * @data: pointer of data to write
249  * @nbytes: number of bytes to write
250  *
251  * Write @nbytes bytes of @data to #GstBitWriter.
252  *
253  * Returns: %TRUE if successful, %FALSE otherwise.
254  */
255 gboolean
256 gst_bit_writer_put_bytes(
257     GstBitWriter *bitwriter,
258     const guint8 *data,
259     guint nbytes
260 )
261 {
262     return _gst_bit_writer_put_bytes_inline(bitwriter, data, nbytes);
263 }
264
265 /**
266  * gst_bit_writer_align_bytes:
267  * @bitwriter: a #GstBitWriter instance
268  * @trailing_bit: trailing bits of last byte, 0 or 1
269  *
270  * Write trailing bit to align last byte of @data. @trailing_bit can only be 1 or 0.
271  *
272  * Returns: %TRUE if successful, %FALSE otherwise.
273  */
274 gboolean
275 gst_bit_writer_align_bytes(GstBitWriter *bitwriter, guint8 trailing_bit)
276 {
277     return _gst_bit_writer_align_bytes_inline(bitwriter, trailing_bit);
278 }