src/pulsecore/sink-input.h

   1 #ifndef foopulsesinkinputhfoo
   2 #define foopulsesinkinputhfoo
   3
   4 /***
   5   This file is part of PulseAudio.
   6
   7   Copyright 2004-2006 Lennart Poettering
   8   Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
   9
  10   PulseAudio is free software; you can redistribute it and/or modify
  11   it under the terms of the GNU Lesser General Public License as published
  12   by the Free Software Foundation; either version 2.1 of the License,
  13   or (at your option) any later version.
  14
  15   PulseAudio is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with PulseAudio; if not, write to the Free Software
  22   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  23   USA.
  24 ***/
  25
  26 #include <inttypes.h>
  27
  28 typedef struct pa_sink_input pa_sink_input;
  29
  30 #include <pulse/sample.h>
  31 #include <pulsecore/hook-list.h>
  32 #include <pulsecore/memblockq.h>
  33 #include <pulsecore/resampler.h>
  34 #include <pulsecore/module.h>
  35 #include <pulsecore/client.h>
  36 #include <pulsecore/sink.h>
  37 #include <pulsecore/core.h>
  38
  39 typedef enum pa_sink_input_state {
  40     PA_SINK_INPUT_INIT,         /*< The stream is not active yet, because pa_sink_put() has not been called yet */
  41     PA_SINK_INPUT_DRAINED,      /*< The stream stopped playing because there was no data to play */
  42     PA_SINK_INPUT_RUNNING,      /*< The stream is alive and kicking */
  43     PA_SINK_INPUT_CORKED,       /*< The stream was corked on user request */
  44     PA_SINK_INPUT_UNLINKED      /*< The stream is dead */
  45 } pa_sink_input_state_t;
  46
  47 static inline pa_bool_t PA_SINK_INPUT_IS_LINKED(pa_sink_input_state_t x) {
  48     return x == PA_SINK_INPUT_DRAINED || x == PA_SINK_INPUT_RUNNING || x == PA_SINK_INPUT_CORKED;
  49 }
  50
  51 typedef enum pa_sink_input_flags {
  52     PA_SINK_INPUT_VARIABLE_RATE = 1,
  53     PA_SINK_INPUT_DONT_MOVE = 2,
  54     PA_SINK_INPUT_START_CORKED = 4,
  55     PA_SINK_INPUT_NO_REMAP = 8,
  56     PA_SINK_INPUT_NO_REMIX = 16,
  57     PA_SINK_INPUT_FIX_FORMAT = 32,
  58     PA_SINK_INPUT_FIX_RATE = 64,
  59     PA_SINK_INPUT_FIX_CHANNELS = 128,
  60     PA_SINK_INPUT_DONT_INHIBIT_AUTO_SUSPEND = 256,
  61     PA_SINK_INPUT_FAIL_ON_SUSPEND = 512
  62 } pa_sink_input_flags_t;
  63
  64 struct pa_sink_input {
  65     pa_msgobject parent;
  66
  67     uint32_t index;
  68     pa_core *core;
  69
  70     /* Please note that this state should only be read with
  71      * pa_sink_input_get_state(). That function will transparently
  72      * merge the thread_info.drained value in. */
  73     pa_sink_input_state_t state;
  74     pa_sink_input_flags_t flags;
  75
  76     char *driver;                       /* may be NULL */
  77     pa_proplist *proplist;
  78
  79     pa_module *module;                  /* may be NULL */
  80     pa_client *client;                  /* may be NULL */
  81
  82     pa_sink *sink; /* NULL while we are being moved */
  83
  84     /* A sink input may be connected to multiple source outputs
  85      * directly, so that they don't get mixed data of the entire
  86      * source. */
  87     pa_idxset *direct_outputs;
  88
  89     pa_sample_spec sample_spec;
  90     pa_channel_map channel_map;
  91
  92     pa_sink_input *sync_prev, *sync_next;
  93
  94     pa_cvolume virtual_volume, soft_volume, volume_factor;
  95     pa_bool_t muted:1;
  96
  97     /* if TRUE then the source we are connected to and/or the volume
  98      * set is worth remembering, i.e. was explicitly chosen by the
  99      * user and not automatically. module-stream-restore looks for
 100      * this.*/
 101     pa_bool_t save_sink:1, save_volume:1, save_muted:1;
 102
 103     pa_resample_method_t requested_resample_method, actual_resample_method;
 104
 105     /* Returns the chunk of audio data and drops it from the
 106      * queue. Returns -1 on failure. Called from IO thread context. If
 107      * data needs to be generated from scratch then please in the
 108      * specified length request_nbytes. This is an optimization
 109      * only. If less data is available, it's fine to return a smaller
 110      * block. If more data is already ready, it is better to return
 111      * the full block. */
 112     int (*pop) (pa_sink_input *i, size_t request_nbytes, pa_memchunk *chunk); /* may NOT be NULL */
 113
 114     /* Rewind the queue by the specified number of bytes. Called just
 115      * before peek() if it is called at all. Only called if the sink
 116      * input driver ever plans to call
 117      * pa_sink_input_request_rewind(). Called from IO context. */
 118     void (*process_rewind) (pa_sink_input *i, size_t nbytes);     /* may NOT be NULL */
 119
 120     /* Called whenever the maximum rewindable size of the sink
 121      * changes. Called from IO context. */
 122     void (*update_max_rewind) (pa_sink_input *i, size_t nbytes); /* may be NULL */
 123
 124     /* Called whenever the maximum request size of the sink
 125      * changes. Called from IO context. */
 126     void (*update_max_request) (pa_sink_input *i, size_t nbytes); /* may be NULL */
 127
 128     /* Called whenever the configured latency of the sink
 129      * changes. Called from IO context. */
 130     void (*update_sink_requested_latency) (pa_sink_input *i); /* may be NULL */
 131
 132     /* Called whenver the latency range of the sink changes. Called
 133      * from IO context. */
 134     void (*update_sink_latency_range) (pa_sink_input *i); /* may be NULL */
 135
 136     /* If non-NULL this function is called when the input is first
 137      * connected to a sink or when the rtpoll/asyncmsgq fields
 138      * change. You usually don't need to implement this function
 139      * unless you rewrite a sink that is piggy-backed onto
 140      * another. Called from IO thread context */
 141     void (*attach) (pa_sink_input *i);           /* may be NULL */
 142
 143     /* If non-NULL this function is called when the output is
 144      * disconnected from its sink. Called from IO thread context */
 145     void (*detach) (pa_sink_input *i);           /* may be NULL */
 146
 147     /* If non-NULL called whenever the sink this input is attached
 148      * to suspends or resumes. Called from main context */
 149     void (*suspend) (pa_sink_input *i, pa_bool_t b);   /* may be NULL */
 150
 151     /* If non-NULL called whenever the sink input is moved to a new
 152      * sink. Called from main context after the sink input has been
 153      * detached from the old sink and before it has been attached to
 154      * the new sink. */
 155     void (*moving) (pa_sink_input *i, pa_sink *dest);   /* may be NULL */
 156
 157     /* Supposed to unlink and destroy this stream. Called from main
 158      * context. */
 159     void (*kill) (pa_sink_input *i);             /* may NOT be NULL */
 160
 161     /* Return the current latency (i.e. length of bufferd audio) of
 162     this stream. Called from main context. This is added to what the
 163     PA_SINK_INPUT_MESSAGE_GET_LATENCY message sent to the IO thread
 164     returns */
 165     pa_usec_t (*get_latency) (pa_sink_input *i); /* may be NULL */
 166
 167     /* If non-NULL this function is called from thread context if the
 168      * state changes. The old state is found in thread_info.state.  */
 169     void (*state_change) (pa_sink_input *i, pa_sink_input_state_t state); /* may be NULL */
 170
 171     /* If non-NULL this function is called before this sink input is
 172      * move to a sink and if it returns FALSE the move will not
 173      * be allowed */
 174     pa_bool_t (*may_move_to) (pa_sink_input *i, pa_sink *s); /* may be NULL */
 175
 176     /* If non-NULL this function is used to dispatch asynchronous
 177      * control events. */
 178     void (*send_event)(pa_sink_input *i, const char *event, pa_proplist* data);
 179
 180     struct {
 181         pa_sink_input_state_t state;
 182         pa_atomic_t drained;
 183
 184         pa_cvolume soft_volume;
 185         pa_bool_t muted:1;
 186
 187         pa_bool_t attached:1; /* True only between ->attach() and ->detach() calls */
 188
 189         /* 0: rewrite nothing, (size_t) -1: rewrite everything, otherwise how many bytes to rewrite */
 190         pa_bool_t rewrite_flush:1, dont_rewind_render:1;
 191         size_t rewrite_nbytes;
 192         uint64_t underrun_for, playing_for;
 193
 194         pa_sample_spec sample_spec;
 195
 196         pa_resampler *resampler;                     /* may be NULL */
 197
 198         /* We maintain a history of resampled audio data here. */
 199         pa_memblockq *render_memblockq;
 200
 201         pa_sink_input *sync_prev, *sync_next;
 202
 203         /* The requested latency for the sink */
 204         pa_usec_t requested_sink_latency;
 205
 206         pa_hashmap *direct_outputs;
 207     } thread_info;
 208
 209     void *userdata;
 210 };
 211
 212 PA_DECLARE_CLASS(pa_sink_input);
 213 #define PA_SINK_INPUT(o) pa_sink_input_cast(o)
 214
 215 enum {
 216     PA_SINK_INPUT_MESSAGE_SET_SOFT_VOLUME,
 217     PA_SINK_INPUT_MESSAGE_SET_SOFT_MUTE,
 218     PA_SINK_INPUT_MESSAGE_GET_LATENCY,
 219     PA_SINK_INPUT_MESSAGE_SET_RATE,
 220     PA_SINK_INPUT_MESSAGE_SET_STATE,
 221     PA_SINK_INPUT_MESSAGE_SET_REQUESTED_LATENCY,
 222     PA_SINK_INPUT_MESSAGE_GET_REQUESTED_LATENCY,
 223     PA_SINK_INPUT_MESSAGE_MAX
 224 };
 225
 226 typedef struct pa_sink_input_send_event_hook_data {
 227     pa_sink_input *sink_input;
 228     const char *event;
 229     pa_proplist *data;
 230 } pa_sink_input_send_event_hook_data;
 231
 232 typedef struct pa_sink_input_new_data {
 233     pa_proplist *proplist;
 234
 235     const char *driver;
 236     pa_module *module;
 237     pa_client *client;
 238
 239     pa_sink *sink;
 240
 241     pa_resample_method_t resample_method;
 242
 243     pa_sink_input *sync_base;
 244
 245     pa_sample_spec sample_spec;
 246     pa_channel_map channel_map;
 247
 248     pa_cvolume volume, volume_factor;
 249     pa_bool_t muted:1;
 250
 251     pa_bool_t sample_spec_is_set:1;
 252     pa_bool_t channel_map_is_set:1;
 253
 254     pa_bool_t volume_is_set:1, volume_factor_is_set:1;
 255     pa_bool_t muted_is_set:1;
 256
 257     pa_bool_t volume_is_absolute:1;
 258
 259     pa_bool_t save_sink:1, save_volume:1, save_muted:1;
 260 } pa_sink_input_new_data;
 261
 262 pa_sink_input_new_data* pa_sink_input_new_data_init(pa_sink_input_new_data *data);
 263 void pa_sink_input_new_data_set_sample_spec(pa_sink_input_new_data *data, const pa_sample_spec *spec);
 264 void pa_sink_input_new_data_set_channel_map(pa_sink_input_new_data *data, const pa_channel_map *map);
 265 void pa_sink_input_new_data_set_volume(pa_sink_input_new_data *data, const pa_cvolume *volume);
 266 void pa_sink_input_new_data_apply_volume_factor(pa_sink_input_new_data *data, const pa_cvolume *volume_factor);
 267 void pa_sink_input_new_data_set_muted(pa_sink_input_new_data *data, pa_bool_t mute);
 268 void pa_sink_input_new_data_done(pa_sink_input_new_data *data);
 269
 270 /* To be called by the implementing module only */
 271
 272 int pa_sink_input_new(
 273         pa_sink_input **i,
 274         pa_core *core,
 275         pa_sink_input_new_data *data,
 276         pa_sink_input_flags_t flags);
 277
 278 void pa_sink_input_put(pa_sink_input *i);
 279 void pa_sink_input_unlink(pa_sink_input* i);
 280
 281 void pa_sink_input_set_name(pa_sink_input *i, const char *name);
 282
 283 pa_usec_t pa_sink_input_set_requested_latency(pa_sink_input *i, pa_usec_t usec);
 284
 285 /* Request that the specified number of bytes already written out to
 286 the hw device is rewritten, if possible.  Please note that this is
 287 only a kind request. The sink driver may not be able to fulfill it
 288 fully -- or at all. If the request for a rewrite was successful, the
 289 sink driver will call ->rewind() and pass the number of bytes that
 290 could be rewound in the HW device. This functionality is required for
 291 implementing the "zero latency" write-through functionality. */
 292 void pa_sink_input_request_rewind(pa_sink_input *i, size_t nbytes, pa_bool_t rewrite, pa_bool_t flush, pa_bool_t dont_rewind_render);
 293
 294 void pa_sink_input_cork(pa_sink_input *i, pa_bool_t b);
 295
 296 int pa_sink_input_set_rate(pa_sink_input *i, uint32_t rate);
 297
 298 /* Callable by everyone from main thread*/
 299
 300 /* External code may request disconnection with this function */
 301 void pa_sink_input_kill(pa_sink_input*i);
 302
 303 pa_usec_t pa_sink_input_get_latency(pa_sink_input *i, pa_usec_t *sink_latency);
 304
 305 void pa_sink_input_set_volume(pa_sink_input *i, const pa_cvolume *volume, pa_bool_t save);
 306 const pa_cvolume *pa_sink_input_get_volume(pa_sink_input *i);
 307 pa_cvolume *pa_sink_input_get_relative_volume(pa_sink_input *i, pa_cvolume *v);
 308 void pa_sink_input_set_mute(pa_sink_input *i, pa_bool_t mute, pa_bool_t save);
 309 pa_bool_t pa_sink_input_get_mute(pa_sink_input *i);
 310 void pa_sink_input_update_proplist(pa_sink_input *i, pa_update_mode_t mode, pa_proplist *p);
 311
 312 pa_resample_method_t pa_sink_input_get_resample_method(pa_sink_input *i);
 313
 314 void pa_sink_input_send_event(pa_sink_input *i, const char *name, pa_proplist *data);
 315
 316 int pa_sink_input_move_to(pa_sink_input *i, pa_sink *dest, pa_bool_t save);
 317 pa_bool_t pa_sink_input_may_move(pa_sink_input *i); /* may this sink input move at all? */
 318 pa_bool_t pa_sink_input_may_move_to(pa_sink_input *i, pa_sink *dest); /* may this sink input move to this sink? */
 319
 320 /* The same as pa_sink_input_move_to() but in two seperate steps,
 321  * first the detaching from the old sink, then the attaching to the
 322  * new sink */
 323 int pa_sink_input_start_move(pa_sink_input *i);
 324 int pa_sink_input_finish_move(pa_sink_input *i, pa_sink *dest, pa_bool_t save);
 325
 326 pa_sink_input_state_t pa_sink_input_get_state(pa_sink_input *i);
 327
 328 pa_usec_t pa_sink_input_get_requested_latency(pa_sink_input *i);
 329
 330 /* To be used exclusively by the sink driver IO thread */
 331
 332 void pa_sink_input_peek(pa_sink_input *i, size_t length, pa_memchunk *chunk, pa_cvolume *volume);
 333 void pa_sink_input_drop(pa_sink_input *i, size_t length);
 334 void pa_sink_input_process_rewind(pa_sink_input *i, size_t nbytes /* in the sink's sample spec */);
 335 void pa_sink_input_update_max_rewind(pa_sink_input *i, size_t nbytes  /* in the sink's sample spec */);
 336 void pa_sink_input_update_max_request(pa_sink_input *i, size_t nbytes  /* in the sink's sample spec */);
 337
 338 void pa_sink_input_set_state_within_thread(pa_sink_input *i, pa_sink_input_state_t state);
 339
 340 int pa_sink_input_process_msg(pa_msgobject *o, int code, void *userdata, int64_t offset, pa_memchunk *chunk);
 341
 342 pa_usec_t pa_sink_input_set_requested_latency_within_thread(pa_sink_input *i, pa_usec_t usec);
 343
 344 pa_bool_t pa_sink_input_safe_to_remove(pa_sink_input *i);
 345
 346 pa_memchunk* pa_sink_input_get_silence(pa_sink_input *i, pa_memchunk *ret);
 347
 348 #endif