1 /*

     2  * This file is part of Libav.

     3  *

     4  * Libav 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  * Libav 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 Libav; 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 Libav

    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  * Get the packed alternative form of the given sample format.

    80  *

    81  * If the passed sample_fmt is already in packed format, the format returned is

    82  * the same as the input.

    83  *

    84  * @return  the packed alternative form of the given sample format or

    85             AV_SAMPLE_FMT_NONE on error.

    86  */

    87 enum AVSampleFormat av_get_packed_sample_fmt(enum AVSampleFormat sample_fmt);

    88 

    89 /**

    90  * Get the planar alternative form of the given sample format.

    91  *

    92  * If the passed sample_fmt is already in planar format, the format returned is

    93  * the same as the input.

    94  *

    95  * @return  the planar alternative form of the given sample format or

    96             AV_SAMPLE_FMT_NONE on error.

    97  */

    98 enum AVSampleFormat av_get_planar_sample_fmt(enum AVSampleFormat sample_fmt);

    99 

   100 /**

   101  * Generate a string corresponding to the sample format with

   102  * sample_fmt, or a header if sample_fmt is negative.

   103  *

   104  * @param buf the buffer where to write the string

   105  * @param buf_size the size of buf

   106  * @param sample_fmt the number of the sample format to print the

   107  * corresponding info string, or a negative value to print the

   108  * corresponding header.

   109  * @return the pointer to the filled buffer or NULL if sample_fmt is

   110  * unknown or in case of other errors

   111  */

   112 char *av_get_sample_fmt_string(char *buf, int buf_size, enum AVSampleFormat sample_fmt);

   113 

   114 #if FF_API_GET_BITS_PER_SAMPLE_FMT

   115 /**

   116  * @deprecated Use av_get_bytes_per_sample() instead.

   117  */

   118 attribute_deprecated

   119 int av_get_bits_per_sample_fmt(enum AVSampleFormat sample_fmt);

   120 #endif

   121 

   122 /**

   123  * Return number of bytes per sample.

   124  *

   125  * @param sample_fmt the sample format

   126  * @return number of bytes per sample or zero if unknown for the given

   127  * sample format

   128  */

   129 int av_get_bytes_per_sample(enum AVSampleFormat sample_fmt);

   130 

   131 /**

   132  * Check if the sample format is planar.

   133  *

   134  * @param sample_fmt the sample format to inspect

   135  * @return 1 if the sample format is planar, 0 if it is interleaved

   136  */

   137 int av_sample_fmt_is_planar(enum AVSampleFormat sample_fmt);

   138 

   139 /**

   140  * Get the required buffer size for the given audio parameters.

   141  *

   142  * @param[out] linesize calculated linesize, may be NULL

   143  * @param nb_channels   the number of channels

   144  * @param nb_samples    the number of samples in a single channel

   145  * @param sample_fmt    the sample format

   146  * @param align         buffer size alignment (0 = default, 1 = no alignment)

   147  * @return              required buffer size, or negative error code on failure

   148  */

   149 int av_samples_get_buffer_size(int *linesize, int nb_channels, int nb_samples,

   150                                enum AVSampleFormat sample_fmt, int align);

   151 

   152 /**

   153  * Fill channel data pointers and linesize for samples with sample

   154  * format sample_fmt.

   155  *

   156  * The pointers array is filled with the pointers to the samples data:

   157  * for planar, set the start point of each channel's data within the buffer,

   158  * for packed, set the start point of the entire buffer only.

   159  *

   160  * The linesize array is filled with the aligned size of each channel's data

   161  * buffer for planar layout, or the aligned size of the buffer for all channels

   162  * for packed layout.

   163  *

   164  * @see enum AVSampleFormat

   165  * The documentation for AVSampleFormat describes the data layout.

   166  *

   167  * @param[out] audio_data  array to be filled with the pointer for each channel

   168  * @param[out] linesize    calculated linesize, may be NULL

   169  * @param buf              the pointer to a buffer containing the samples

   170  * @param nb_channels      the number of channels

   171  * @param nb_samples       the number of samples in a single channel

   172  * @param sample_fmt       the sample format

   173  * @param align            buffer size alignment (0 = default, 1 = no alignment)

   174  * @return                 0 on success or a negative error code on failure

   175  */

   176 int av_samples_fill_arrays(uint8_t **audio_data, int *linesize,

   177                            const uint8_t *buf,

   178                            int nb_channels, int nb_samples,

   179                            enum AVSampleFormat sample_fmt, int align);

   180 

   181 /**

   182  * Allocate a samples buffer for nb_samples samples, and fill data pointers and

   183  * linesize accordingly.

   184  * The allocated samples buffer can be freed by using av_freep(&audio_data[0])

   185  * Allocated data will be initialized to silence.

   186  *

   187  * @see enum AVSampleFormat

   188  * The documentation for AVSampleFormat describes the data layout.

   189  *

   190  * @param[out] audio_data  array to be filled with the pointer for each channel

   191  * @param[out] linesize    aligned size for audio buffer(s), may be NULL

   192  * @param nb_channels      number of audio channels

   193  * @param nb_samples       number of samples per channel

   194  * @param align            buffer size alignment (0 = default, 1 = no alignment)

   195  * @return                 0 on success or a negative error code on failure

   196  * @see av_samples_fill_arrays()

   197  */

   198 int av_samples_alloc(uint8_t **audio_data, int *linesize, int nb_channels,

   199                      int nb_samples, enum AVSampleFormat sample_fmt, int align);

   200 

   201 /**

   202  * Copy samples from src to dst.

   203  *

   204  * @param dst destination array of pointers to data planes

   205  * @param src source array of pointers to data planes

   206  * @param dst_offset offset in samples at which the data will be written to dst

   207  * @param src_offset offset in samples at which the data will be read from src

   208  * @param nb_samples number of samples to be copied

   209  * @param nb_channels number of audio channels

   210  * @param sample_fmt audio sample format

   211  */

   212 int av_samples_copy(uint8_t **dst, uint8_t * const *src, int dst_offset,

   213                     int src_offset, int nb_samples, int nb_channels,

   214                     enum AVSampleFormat sample_fmt);

   215 

   216 /**

   217  * Fill an audio buffer with silence.

   218  *

   219  * @param audio_data  array of pointers to data planes

   220  * @param offset      offset in samples at which to start filling

   221  * @param nb_samples  number of samples to fill

   222  * @param nb_channels number of audio channels

   223  * @param sample_fmt  audio sample format

   224  */

   225 int av_samples_set_silence(uint8_t **audio_data, int offset, int nb_samples,

   226                            int nb_channels, enum AVSampleFormat sample_fmt);

   227 

   228 #endif /* AVUTIL_SAMPLEFMT_H */