FFmpeg
Main Page
Related Pages
Modules
Namespaces
Data Structures
Files
Examples
File List
Globals
All
Data Structures
Namespaces
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
libavutil
samplefmt.h
Go to the documentation of this file.
1
/*
2
* This file is part of FFmpeg.
3
*
4
* FFmpeg is free software; you can redistribute it and/or
5
* modify it under the terms of the GNU Lesser General Public
6
* License as published by the Free Software Foundation; either
7
* version 2.1 of the License, or (at your option) any later version.
8
*
9
* FFmpeg is distributed in the hope that it will be useful,
10
* but WITHOUT ANY WARRANTY; without even the implied warranty of
11
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12
* Lesser General Public License for more details.
13
*
14
* You should have received a copy of the GNU Lesser General Public
15
* License along with FFmpeg; if not, write to the Free Software
16
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17
*/
18
19
#ifndef AVUTIL_SAMPLEFMT_H
20
#define AVUTIL_SAMPLEFMT_H
21
22
#include <stdint.h>
23
24
#include "
avutil.h
"
25
#include "
attributes.h
"
26
27
/**
28
* Audio Sample Formats
29
*
30
* @par
31
* The data described by the sample format is always in native-endian order.
32
* Sample values can be expressed by native C types, hence the lack of a signed
33
* 24-bit sample format even though it is a common raw audio data format.
34
*
35
* @par
36
* The floating-point formats are based on full volume being in the range
37
* [-1.0, 1.0]. Any values outside this range are beyond full volume level.
38
*
39
* @par
40
* The data layout as used in av_samples_fill_arrays() and elsewhere in FFmpeg
41
* (such as AVFrame in libavcodec) is as follows:
42
*
43
* For planar sample formats, each audio channel is in a separate data plane,
44
* and linesize is the buffer size, in bytes, for a single plane. All data
45
* planes must be the same size. For packed sample formats, only the first data
46
* plane is used, and samples for each channel are interleaved. In this case,
47
* linesize is the buffer size, in bytes, for the 1 plane.
48
*/
49
enum
AVSampleFormat
{
50
AV_SAMPLE_FMT_NONE
= -1,
51
AV_SAMPLE_FMT_U8
,
///< unsigned 8 bits
52
AV_SAMPLE_FMT_S16
,
///< signed 16 bits
53
AV_SAMPLE_FMT_S32
,
///< signed 32 bits
54
AV_SAMPLE_FMT_FLT
,
///< float
55
AV_SAMPLE_FMT_DBL
,
///< double
56
57
AV_SAMPLE_FMT_U8P
,
///< unsigned 8 bits, planar
58
AV_SAMPLE_FMT_S16P
,
///< signed 16 bits, planar
59
AV_SAMPLE_FMT_S32P
,
///< signed 32 bits, planar
60
AV_SAMPLE_FMT_FLTP
,
///< float, planar
61
AV_SAMPLE_FMT_DBLP
,
///< double, planar
62
63
AV_SAMPLE_FMT_NB
///< Number of sample formats. DO NOT USE if linking dynamically
64
};
65
66
/**
67
* Return the name of sample_fmt, or NULL if sample_fmt is not
68
* recognized.
69
*/
70
const
char
*
av_get_sample_fmt_name
(
enum
AVSampleFormat
sample_fmt);
71
72
/**
73
* Return a sample format corresponding to name, or AV_SAMPLE_FMT_NONE
74
* on error.
75
*/
76
enum
AVSampleFormat
av_get_sample_fmt
(
const
char
*
name
);
77
78
/**
79
* Return the planar<->packed alternative form of the given sample format, or
80
* AV_SAMPLE_FMT_NONE on error. If the passed sample_fmt is already in the
81
* requested planar/packed format, the format returned is the same as the
82
* input.
83
*/
84
enum
AVSampleFormat
av_get_alt_sample_fmt
(
enum
AVSampleFormat
sample_fmt,
int
planar);
85
86
/**
87
* Get the packed alternative form of the given sample format.
88
*
89
* If the passed sample_fmt is already in packed format, the format returned is
90
* the same as the input.
91
*
92
* @return the packed alternative form of the given sample format or
93
AV_SAMPLE_FMT_NONE on error.
94
*/
95
enum
AVSampleFormat
av_get_packed_sample_fmt
(
enum
AVSampleFormat
sample_fmt);
96
97
/**
98
* Get the planar alternative form of the given sample format.
99
*
100
* If the passed sample_fmt is already in planar format, the format returned is
101
* the same as the input.
102
*
103
* @return the planar alternative form of the given sample format or
104
AV_SAMPLE_FMT_NONE on error.
105
*/
106
enum
AVSampleFormat
av_get_planar_sample_fmt
(
enum
AVSampleFormat
sample_fmt);
107
108
/**
109
* Generate a string corresponding to the sample format with
110
* sample_fmt, or a header if sample_fmt is negative.
111
*
112
* @param buf the buffer where to write the string
113
* @param buf_size the size of buf
114
* @param sample_fmt the number of the sample format to print the
115
* corresponding info string, or a negative value to print the
116
* corresponding header.
117
* @return the pointer to the filled buffer or NULL if sample_fmt is
118
* unknown or in case of other errors
119
*/
120
char
*
av_get_sample_fmt_string
(
char
*
buf
,
int
buf_size,
enum
AVSampleFormat
sample_fmt);
121
122
#if FF_API_GET_BITS_PER_SAMPLE_FMT
123
/**
124
* @deprecated Use av_get_bytes_per_sample() instead.
125
*/
126
attribute_deprecated
127
int
av_get_bits_per_sample_fmt
(
enum
AVSampleFormat
sample_fmt);
128
#endif
129
130
/**
131
* Return number of bytes per sample.
132
*
133
* @param sample_fmt the sample format
134
* @return number of bytes per sample or zero if unknown for the given
135
* sample format
136
*/
137
int
av_get_bytes_per_sample
(
enum
AVSampleFormat
sample_fmt);
138
139
/**
140
* Check if the sample format is planar.
141
*
142
* @param sample_fmt the sample format to inspect
143
* @return 1 if the sample format is planar, 0 if it is interleaved
144
*/
145
int
av_sample_fmt_is_planar
(
enum
AVSampleFormat
sample_fmt);
146
147
/**
148
* Get the required buffer size for the given audio parameters.
149
*
150
* @param[out] linesize calculated linesize, may be NULL
151
* @param nb_channels the number of channels
152
* @param nb_samples the number of samples in a single channel
153
* @param sample_fmt the sample format
154
* @param align buffer size alignment (0 = default, 1 = no alignment)
155
* @return required buffer size, or negative error code on failure
156
*/
157
int
av_samples_get_buffer_size
(
int
*linesize,
int
nb_channels
,
int
nb_samples,
158
enum
AVSampleFormat
sample_fmt,
int
align
);
159
160
/**
161
* Fill plane data pointers and linesize for samples with sample
162
* format sample_fmt.
163
*
164
* The audio_data array is filled with the pointers to the samples data planes:
165
* for planar, set the start point of each channel's data within the buffer,
166
* for packed, set the start point of the entire buffer only.
167
*
168
* The value pointed to by linesize is set to the aligned size of each
169
* channel's data buffer for planar layout, or to the aligned size of the
170
* buffer for all channels for packed layout.
171
*
172
* The buffer in buf must be big enough to contain all the samples
173
* (use av_samples_get_buffer_size() to compute its minimum size),
174
* otherwise the audio_data pointers will point to invalid data.
175
*
176
* @see enum AVSampleFormat
177
* The documentation for AVSampleFormat describes the data layout.
178
*
179
* @param[out] audio_data array to be filled with the pointer for each channel
180
* @param[out] linesize calculated linesize, may be NULL
181
* @param buf the pointer to a buffer containing the samples
182
* @param nb_channels the number of channels
183
* @param nb_samples the number of samples in a single channel
184
* @param sample_fmt the sample format
185
* @param align buffer size alignment (0 = default, 1 = no alignment)
186
* @return >=0 on success or a negative error code on failure
187
* @todo return minimum size in bytes required for the buffer in case
188
* of success at the next bump
189
*/
190
int
av_samples_fill_arrays
(
uint8_t
**audio_data,
int
*linesize,
191
const
uint8_t
*
buf
,
192
int
nb_channels
,
int
nb_samples,
193
enum
AVSampleFormat
sample_fmt,
int
align
);
194
195
/**
196
* Allocate a samples buffer for nb_samples samples, and fill data pointers and
197
* linesize accordingly.
198
* The allocated samples buffer can be freed by using av_freep(&audio_data[0])
199
* Allocated data will be initialized to silence.
200
*
201
* @see enum AVSampleFormat
202
* The documentation for AVSampleFormat describes the data layout.
203
*
204
* @param[out] audio_data array to be filled with the pointer for each channel
205
* @param[out] linesize aligned size for audio buffer(s), may be NULL
206
* @param nb_channels number of audio channels
207
* @param nb_samples number of samples per channel
208
* @param align buffer size alignment (0 = default, 1 = no alignment)
209
* @return >=0 on success or a negative error code on failure
210
* @todo return the size of the allocated buffer in case of success at the next bump
211
* @see av_samples_fill_arrays()
212
* @see av_samples_alloc_array_and_samples()
213
*/
214
int
av_samples_alloc
(
uint8_t
**audio_data,
int
*linesize,
int
nb_channels
,
215
int
nb_samples,
enum
AVSampleFormat
sample_fmt,
int
align
);
216
217
/**
218
* Allocate a data pointers array, samples buffer for nb_samples
219
* samples, and fill data pointers and linesize accordingly.
220
*
221
* This is the same as av_samples_alloc(), but also allocates the data
222
* pointers array.
223
*
224
* @see av_samples_alloc()
225
*/
226
int
av_samples_alloc_array_and_samples
(
uint8_t
***audio_data,
int
*linesize,
int
nb_channels
,
227
int
nb_samples,
enum
AVSampleFormat
sample_fmt,
int
align
);
228
229
/**
230
* Copy samples from src to dst.
231
*
232
* @param dst destination array of pointers to data planes
233
* @param src source array of pointers to data planes
234
* @param dst_offset offset in samples at which the data will be written to dst
235
* @param src_offset offset in samples at which the data will be read from src
236
* @param nb_samples number of samples to be copied
237
* @param nb_channels number of audio channels
238
* @param sample_fmt audio sample format
239
*/
240
int
av_samples_copy
(
uint8_t
**dst,
uint8_t
*
const
*
src
,
int
dst_offset,
241
int
src_offset,
int
nb_samples,
int
nb_channels
,
242
enum
AVSampleFormat
sample_fmt);
243
244
/**
245
* Fill an audio buffer with silence.
246
*
247
* @param audio_data array of pointers to data planes
248
* @param offset offset in samples at which to start filling
249
* @param nb_samples number of samples to fill
250
* @param nb_channels number of audio channels
251
* @param sample_fmt audio sample format
252
*/
253
int
av_samples_set_silence
(
uint8_t
**audio_data,
int
offset
,
int
nb_samples,
254
int
nb_channels
,
enum
AVSampleFormat
sample_fmt);
255
256
#endif
/* AVUTIL_SAMPLEFMT_H */
Generated on Wed Jul 10 2013 23:48:16 for FFmpeg by
1.8.2