1 /* GStreamer 2 * Copyright (C) <2011> Wim Taymans <wim.taymans@gmail.com> 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Library General Public 6 * License as published by the Free Software Foundation; either 7 * version 2 of the License, or (at your option) any later version. 8 * 9 * This library 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 * Library General Public License for more details. 13 * 14 * You should have received a copy of the GNU Library General Public 15 * License along with this library; if not, write to the 16 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 17 * Boston, MA 02110-1301, USA. 18 */ 19 20 #ifndef __GST_AUDIO_META_H__ 21 #define __GST_AUDIO_META_H__ 22 23 #include <gst/audio/audio.h> 24 25 G_BEGIN_DECLS 26 27 #define GST_AUDIO_DOWNMIX_META_API_TYPE (gst_audio_downmix_meta_api_get_type()) 28 #define GST_AUDIO_DOWNMIX_META_INFO (gst_audio_downmix_meta_get_info()) 29 30 typedef struct _GstAudioDownmixMeta GstAudioDownmixMeta; 31 32 /** 33 * GstAudioDownmixMeta: 34 * @meta: parent #GstMeta 35 * @from_position: the channel positions of the source 36 * @to_position: the channel positions of the destination 37 * @from_channels: the number of channels of the source 38 * @to_channels: the number of channels of the destination 39 * @matrix: the matrix coefficients. 40 * 41 * Extra buffer metadata describing audio downmixing matrix. This metadata is 42 * attached to audio buffers and contains a matrix to downmix the buffer number 43 * of channels to @channels. 44 * 45 * @matrix is an two-dimensional array of @to_channels times @from_channels 46 * coefficients, i.e. the i-th output channels is constructed by multiplicating 47 * the input channels with the coefficients in @matrix[i] and taking the sum 48 * of the results. 49 */ 50 struct _GstAudioDownmixMeta { 51 GstMeta meta; 52 53 GstAudioChannelPosition *from_position; 54 GstAudioChannelPosition *to_position; 55 gint from_channels, to_channels; 56 gfloat **matrix; 57 }; 58 59 GST_AUDIO_API 60 GType gst_audio_downmix_meta_api_get_type (void); 61 62 GST_AUDIO_API 63 const GstMetaInfo * gst_audio_downmix_meta_get_info (void); 64 65 #define gst_buffer_get_audio_downmix_meta(b) ((GstAudioDownmixMeta*)gst_buffer_get_meta((b), GST_AUDIO_DOWNMIX_META_API_TYPE)) 66 GST_AUDIO_API 67 GstAudioDownmixMeta * gst_buffer_get_audio_downmix_meta_for_channels (GstBuffer *buffer, 68 const GstAudioChannelPosition *to_position, 69 gint to_channels); 70 71 GST_AUDIO_API 72 GstAudioDownmixMeta * gst_buffer_add_audio_downmix_meta (GstBuffer *buffer, 73 const GstAudioChannelPosition *from_position, 74 gint from_channels, 75 const GstAudioChannelPosition *to_position, 76 gint to_channels, 77 const gfloat **matrix); 78 79 80 #define GST_AUDIO_CLIPPING_META_API_TYPE (gst_audio_clipping_meta_api_get_type()) 81 #define GST_AUDIO_CLIPPING_META_INFO (gst_audio_clipping_meta_get_info()) 82 83 typedef struct _GstAudioClippingMeta GstAudioClippingMeta; 84 85 /** 86 * GstAudioClippingMeta: 87 * @meta: parent #GstMeta 88 * @format: GstFormat of @start and @stop, GST_FORMAT_DEFAULT is samples 89 * @start: Amount of audio to clip from start of buffer 90 * @end: Amount of to clip from end of buffer 91 * 92 * Extra buffer metadata describing how much audio has to be clipped from 93 * the start or end of a buffer. This is used for compressed formats, where 94 * the first frame usually has some additional samples due to encoder and 95 * decoder delays, and the last frame usually has some additional samples to 96 * be able to fill the complete last frame. 97 * 98 * This is used to ensure that decoded data in the end has the same amount of 99 * samples, and multiply decoded streams can be gaplessly concatenated. 100 * 101 * Note: If clipping of the start is done by adjusting the segment, this meta 102 * has to be dropped from buffers as otherwise clipping could happen twice. 103 * 104 * Since: 1.8 105 */ 106 struct _GstAudioClippingMeta { 107 GstMeta meta; 108 109 GstFormat format; 110 guint64 start; 111 guint64 end; 112 }; 113 114 GST_AUDIO_API 115 GType gst_audio_clipping_meta_api_get_type (void); 116 117 GST_AUDIO_API 118 const GstMetaInfo * gst_audio_clipping_meta_get_info (void); 119 120 #define gst_buffer_get_audio_clipping_meta(b) ((GstAudioClippingMeta*)gst_buffer_get_meta((b), GST_AUDIO_CLIPPING_META_API_TYPE)) 121 122 GST_AUDIO_API 123 GstAudioClippingMeta * gst_buffer_add_audio_clipping_meta (GstBuffer *buffer, 124 GstFormat format, 125 guint64 start, 126 guint64 end); 127 128 129 #define GST_AUDIO_META_API_TYPE (gst_audio_meta_api_get_type()) 130 #define GST_AUDIO_META_INFO (gst_audio_meta_get_info()) 131 132 typedef struct _GstAudioMeta GstAudioMeta; 133 134 /** 135 * GstAudioMeta: 136 * @meta: parent #GstMeta 137 * @info: the audio properties of the buffer 138 * @samples: the number of valid samples in the buffer 139 * @offsets: the offsets (in bytes) where each channel plane starts in the 140 * buffer or %NULL if the buffer has interleaved layout; if not %NULL, this 141 * is guaranteed to be an array of @info.channels elements 142 * 143 * Buffer metadata describing how data is laid out inside the buffer. This 144 * is useful for non-interleaved (planar) buffers, where it is necessary to 145 * have a place to store where each plane starts and how long each plane is. 146 * 147 * It is a requirement for non-interleaved buffers to have this metadata 148 * attached and to be mapped with gst_audio_buffer_map() in order to ensure 149 * correct handling of clipping and channel reordering. 150 * 151 * The different channels in @offsets are always in the GStreamer channel order. 152 * Zero-copy channel reordering can be implemented by swapping the values in 153 * @offsets. 154 * 155 * It is not allowed for channels to overlap in memory, 156 * i.e. for each i in [0, channels), the range 157 * [@offsets[i], @offsets[i] + @samples * sample_stride) must not overlap 158 * with any other such range. 159 * 160 * It is, however, allowed to have parts of the buffer memory unused, 161 * by using @offsets and @samples in such a way that leave gaps on it. 162 * This is used to implement zero-copy clipping in non-interleaved buffers. 163 * 164 * Obviously, due to the above, it is not safe to infer the 165 * number of valid samples from the size of the buffer. You should always 166 * use the @samples variable of this metadata. 167 * 168 * Note that for interleaved audio it is not a requirement to have this 169 * metadata attached and at the moment of writing, there is actually no use 170 * case to do so. It is, however, allowed to attach it, for some potential 171 * future use case. 172 * 173 * Since: 1.16 174 */ 175 struct _GstAudioMeta { 176 GstMeta meta; 177 178 GstAudioInfo info; 179 gsize samples; 180 gsize *offsets; 181 182 /*< private >*/ 183 gsize priv_offsets_arr[8]; 184 gpointer _gst_reserved[GST_PADDING]; 185 }; 186 187 GST_AUDIO_API 188 GType gst_audio_meta_api_get_type (void); 189 190 GST_AUDIO_API 191 const GstMetaInfo * gst_audio_meta_get_info (void); 192 193 #define gst_buffer_get_audio_meta(b) \ 194 ((GstAudioMeta*)gst_buffer_get_meta((b), GST_AUDIO_META_API_TYPE)) 195 196 GST_AUDIO_API 197 GstAudioMeta * gst_buffer_add_audio_meta (GstBuffer *buffer, 198 const GstAudioInfo *info, 199 gsize samples, gsize offsets[]); 200 201 G_END_DECLS 202 203 #endif /* __GST_AUDIO_META_H__ */ 204