src/pulse/format.h

   1 #ifndef fooformathfoo
   2 #define fooformathfoo
   3
   4 /***
   5   This file is part of PulseAudio.
   6
   7   Copyright 2011 Intel Corporation
   8   Copyright 2011 Collabora Multimedia
   9   Copyright 2011 Arun Raghavan <arun.raghavan@collabora.co.uk>
  10
  11   PulseAudio is free software; you can redistribute it and/or modify
  12   it under the terms of the GNU Lesser General Public License as published
  13   by the Free Software Foundation; either version 2.1 of the License,
  14   or (at your option) any later version.
  15
  16   PulseAudio is distributed in the hope that it will be useful, but
  17   WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19   General Public License for more details.
  20
  21   You should have received a copy of the GNU Lesser General Public License
  22   along with PulseAudio; if not, write to the Free Software
  23   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  24   USA.
  25 ***/
  26
  27 #include <pulse/cdecl.h>
  28 #include <pulse/gccmacro.h>
  29 #include <pulse/proplist.h>
  30 #include <pulse/sample.h>
  31 #include <pulse/channelmap.h>
  32
  33 /** \file
  34  * Utility functions for handling a stream or sink format. */
  35
  36 PA_C_DECL_BEGIN
  37
  38 /** Represents the type of encoding used in a stream or accepted by a sink. \since 1.0 */
  39 typedef enum pa_encoding {
  40     PA_ENCODING_ANY,
  41     /**< Any encoding format, PCM or compressed */
  42
  43     PA_ENCODING_PCM,
  44     /**< Any PCM format */
  45
  46     PA_ENCODING_AC3_IEC61937,
  47     /**< AC3 data encapsulated in IEC 61937 header/padding */
  48
  49     PA_ENCODING_EAC3_IEC61937,
  50     /**< EAC3 data encapsulated in IEC 61937 header/padding */
  51
  52     PA_ENCODING_MPEG_IEC61937,
  53     /**< MPEG-1 or MPEG-2 (Part 3, not AAC) data encapsulated in IEC 61937 header/padding */
  54
  55     PA_ENCODING_DTS_IEC61937,
  56     /**< DTS data encapsulated in IEC 61937 header/padding */
  57
  58     PA_ENCODING_MAX,
  59     /**< Valid encoding types must be less than this value */
  60
  61     PA_ENCODING_INVALID = -1,
  62     /**< Represents an invalid encoding */
  63 } pa_encoding_t;
  64
  65 /** Returns a printable string representing the given encoding type. \since 1.0 */
  66 const char *pa_encoding_to_string(pa_encoding_t e) PA_GCC_CONST;
  67
  68 /** Converts a string of the form returned by \a pa_encoding_to_string() back to a \a pa_encoding_t. \since 1.0 */
  69 pa_encoding_t pa_encoding_from_string(const char *encoding);
  70
  71 /** Represents the format of data provided in a stream or processed by a sink. \since 1.0 */
  72 typedef struct pa_format_info {
  73     pa_encoding_t encoding;
  74     /**< The encoding used for the format */
  75
  76     pa_proplist *plist;
  77     /**< Additional encoding-specific properties such as sample rate, bitrate, etc. */
  78 } pa_format_info;
  79
  80 /** Allocates a new \a pa_format_info structure. Clients must initialise at least the encoding field themselves. \since 1.0 */
  81 pa_format_info* pa_format_info_new(void);
  82
  83 /** Returns a new \a pa_format_info struct and representing the same format as \a src. \since 1.0 */
  84 pa_format_info* pa_format_info_copy(const pa_format_info *src);
  85
  86 /** Frees a \a pa_format_info structure. \since 1.0 */
  87 void pa_format_info_free(pa_format_info *f);
  88
  89 /** Returns non-zero when the format info structure is valid. \since 1.0 */
  90 int pa_format_info_valid(const pa_format_info *f);
  91
  92 /** Returns non-zero when the format info structure represents a PCM (i.e.\ uncompressed data) format. \since 1.0 */
  93 int pa_format_info_is_pcm(const pa_format_info *f);
  94
  95 /** Returns non-zero if the format represented by \a first is a subset of
  96  * the format represented by \a second. This means that \a second must
  97  * have all the fields that \a first does, but the reverse need not
  98  * be true. This is typically expected to be used to check if a
  99  * stream's format is compatible with a given sink. In such a case,
 100  * \a first would be the sink's format and \a second would be the
 101  * stream's. \since 1.0 */
 102 int pa_format_info_is_compatible(pa_format_info *first, pa_format_info *second);
 103
 104 /** Maximum required string length for
 105  * pa_format_info_snprint(). Please note that this value can change
 106  * with any release without warning and without being considered API
 107  * or ABI breakage. You should not use this definition anywhere where
 108  * it might become part of an ABI. \since 1.0 */
 109 #define PA_FORMAT_INFO_SNPRINT_MAX 256
 110
 111 /** Return a human-readable string representing the given format. \since 1.0 */
 112 char *pa_format_info_snprint(char *s, size_t l, const pa_format_info *f);
 113
 114 /** Parse a human-readable string of the form generated by
 115  * \a pa_format_info_snprint() into a pa_format_info structure. \since 1.0 */
 116 pa_format_info* pa_format_info_from_string(const char *str);
 117
 118 /** Utility function to take a \a pa_sample_spec and generate the corresponding \a pa_format_info. \since 2.0 */
 119 pa_format_info* pa_format_info_from_sample_spec(pa_sample_spec *ss, pa_channel_map *map);
 120
 121 /** Utility function to generate a \a pa_sample_spec and \a pa_channel_map corresponding to a given \a pa_format_info. The
 122  * conversion for PCM formats is straight-forward. For non-PCM formats, if there is a fixed size-time conversion (i.e. all
 123  * IEC61937-encapsulated formats), a "fake" sample spec whose size-time conversion corresponds to this format is provided and
 124  * the channel map argument is ignored. For formats with variable size-time conversion, this function will fail. Returns a
 125  * negative integer if conversion failed and 0 on success. \since 2.0 */
 126 int pa_format_info_to_sample_spec(pa_format_info *f, pa_sample_spec *ss, pa_channel_map *map);
 127
 128 /** Represents the type of value type of a property on a \ref pa_format_info. \since 2.0 */
 129 typedef enum pa_prop_type_t {
 130     PA_PROP_TYPE_INT,
 131     /**< Integer property */
 132
 133     PA_PROP_TYPE_INT_RANGE,
 134     /**< Integer range property */
 135
 136     PA_PROP_TYPE_INT_ARRAY,
 137     /**< Integer array property */
 138
 139     PA_PROP_TYPE_STRING,
 140     /**< String property */
 141
 142     PA_PROP_TYPE_STRING_ARRAY,
 143     /**< String array property */
 144
 145     PA_PROP_TYPE_INVALID = -1,
 146     /**< Represents an invalid type */
 147 } pa_prop_type_t;
 148
 149 /** Gets the type of property \a key in a given \ref pa_format_info. \since 2.0 */
 150 pa_prop_type_t pa_format_info_get_prop_type(pa_format_info *f, const char *key);
 151
 152 /** Gets an integer property from the given format info. Returns 0 on success and a negative integer on failure. \since 2.0 */
 153 int pa_format_info_get_prop_int(pa_format_info *f, const char *key, int *v);
 154 /** Gets an integer range property from the given format info. Returns 0 on success and a negative integer on failure.
 155  * \since 2.0 */
 156 int pa_format_info_get_prop_int_range(pa_format_info *f, const char *key, int *min, int *max);
 157 /** Gets an integer array property from the given format info. \a values contains the values and \a n_values contains the
 158  * number of elements. The caller must free \a values using \ref pa_xfree. Returns 0 on success and a negative integer on
 159  * failure. \since 2.0 */
 160 int pa_format_info_get_prop_int_array(pa_format_info *f, const char *key, int **values, int *n_values);
 161 /** Gets a string property from the given format info.  The caller must free the returned string using \ref pa_xfree. Returns
 162  * 0 on success and a negative integer on failure. \since 2.0 */
 163 int pa_format_info_get_prop_string(pa_format_info *f, const char *key, char **v);
 164 /** Gets a string array property from the given format info. \a values contains the values and \a n_values contains
 165  * the number of elements. The caller must free \a values using \ref pa_format_info_free_string_array. Returns 0 on success and
 166  * a negative integer on failure. \since 2.0 */
 167 int pa_format_info_get_prop_string_array(pa_format_info *f, const char *key, char ***values, int *n_values);
 168
 169 /** Frees a string array returned by \ref pa_format_info_get_prop_string_array. \since 2.0 */
 170 void pa_format_info_free_string_array(char **values, int n_values);
 171
 172 /** Sets an integer property on the given format info. \since 1.0 */
 173 void pa_format_info_set_prop_int(pa_format_info *f, const char *key, int value);
 174 /** Sets a property with a list of integer values on the given format info. \since 1.0 */
 175 void pa_format_info_set_prop_int_array(pa_format_info *f, const char *key, const int *values, int n_values);
 176 /** Sets a property which can have any value in a given integer range on the given format info. \since 1.0 */
 177 void pa_format_info_set_prop_int_range(pa_format_info *f, const char *key, int min, int max);
 178 /** Sets a string property on the given format info. \since 1.0 */
 179 void pa_format_info_set_prop_string(pa_format_info *f, const char *key, const char *value);
 180 /** Sets a property with a list of string values on the given format info. \since 1.0 */
 181 void pa_format_info_set_prop_string_array(pa_format_info *f, const char *key, const char **values, int n_values);
 182
 183 /** Convenience method to set the sample format as a property on the given format. \since 1.0 */
 184 void pa_format_info_set_sample_format(pa_format_info *f, pa_sample_format_t sf);
 185 /** Convenience method to set the sampling rate as a property on the given format. \since 1.0 */
 186 void pa_format_info_set_rate(pa_format_info *f, int rate);
 187 /** Convenience method to set the number of channels as a property on the given format. \since 1.0 */
 188 void pa_format_info_set_channels(pa_format_info *f, int channels);
 189 /** Convenience method to set the channel map as a property on the given format. \since 1.0 */
 190 void pa_format_info_set_channel_map(pa_format_info *f, const pa_channel_map *map);
 191
 192 PA_C_DECL_END
 193
 194 #endif