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 <pulse/format.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 #include <pulsecore/mix.h>
  39
  40 typedef enum pa_sink_input_state {
  41     PA_SINK_INPUT_INIT,         /*< The stream is not active yet, because pa_sink_input_put() has not been called yet */
  42     PA_SINK_INPUT_DRAINED,      /*< The stream stopped playing because there was no data to play */
  43     PA_SINK_INPUT_RUNNING,      /*< The stream is alive and kicking */
  44     PA_SINK_INPUT_CORKED,       /*< The stream was corked on user request */
  45     PA_SINK_INPUT_UNLINKED      /*< The stream is dead */
  46     /* FIXME: we need a state for MOVING here */
  47 } pa_sink_input_state_t;
  48
  49 static inline bool PA_SINK_INPUT_IS_LINKED(pa_sink_input_state_t x) {
  50     return x == PA_SINK_INPUT_DRAINED || x == PA_SINK_INPUT_RUNNING || x == PA_SINK_INPUT_CORKED;
  51 }
  52
  53 typedef enum pa_sink_input_flags {
  54     PA_SINK_INPUT_VARIABLE_RATE = 1,
  55     PA_SINK_INPUT_DONT_MOVE = 2,
  56     PA_SINK_INPUT_START_CORKED = 4,
  57     PA_SINK_INPUT_NO_REMAP = 8,
  58     PA_SINK_INPUT_NO_REMIX = 16,
  59     PA_SINK_INPUT_FIX_FORMAT = 32,
  60     PA_SINK_INPUT_FIX_RATE = 64,
  61     PA_SINK_INPUT_FIX_CHANNELS = 128,
  62     PA_SINK_INPUT_DONT_INHIBIT_AUTO_SUSPEND = 256,
  63     PA_SINK_INPUT_NO_CREATE_ON_SUSPEND = 512,
  64     PA_SINK_INPUT_KILL_ON_SUSPEND = 1024,
  65     PA_SINK_INPUT_PASSTHROUGH = 2048,
  66     PA_SINK_INPUT_START_RAMP_MUTED = 4096,
  67 } pa_sink_input_flags_t;
  68
  69 struct pa_sink_input {
  70     pa_msgobject parent;
  71
  72     uint32_t index;
  73     pa_core *core;
  74
  75     /* Please note that this state should only be read with
  76      * pa_sink_input_get_state(). That function will transparently
  77      * merge the thread_info.drained value in. */
  78     pa_sink_input_state_t state;
  79     pa_sink_input_flags_t flags;
  80
  81     char *driver;                       /* may be NULL */
  82     pa_proplist *proplist;
  83
  84     pa_module *module;                  /* may be NULL */
  85     pa_client *client;                  /* may be NULL */
  86
  87     pa_sink *sink;                      /* NULL while we are being moved */
  88     pa_sink *origin_sink;               /* only set by filter sinks */
  89
  90     /* A sink input may be connected to multiple source outputs
  91      * directly, so that they don't get mixed data of the entire
  92      * source. */
  93     pa_idxset *direct_outputs;
  94
  95     pa_sample_spec sample_spec;
  96     pa_channel_map channel_map;
  97     pa_format_info *format;
  98
  99     pa_sink_input *sync_prev, *sync_next;
 100
 101     /* Also see http://pulseaudio.org/wiki/InternalVolumes */
 102     pa_cvolume volume;             /* The volume clients are informed about */
 103     pa_cvolume reference_ratio;    /* The ratio of the stream's volume to the sink's reference volume */
 104     pa_cvolume real_ratio;         /* The ratio of the stream's volume to the sink's real volume */
 105     /* volume_factor is an internally used "additional volume" that can be used
 106      * by modules without having the volume visible to clients. volume_factor
 107      * calculated by merging all the individual items in volume_factor_items.
 108      * Modules must not modify these variables directly, instead
 109      * pa_sink_input_add/remove_volume_factor() have to be used to add and
 110      * remove items, or pa_sink_input_new_data_add_volume_factor() during input
 111      * creation time. */
 112     pa_cvolume volume_factor;
 113     pa_hashmap *volume_factor_items;
 114     pa_cvolume soft_volume;          /* The internal software volume we apply to all PCM data while it passes through. Usually calculated as real_ratio * volume_factor */
 115
 116     pa_cvolume volume_factor_sink; /* A second volume factor in format of the sink this stream is connected to. */
 117     pa_hashmap *volume_factor_sink_items;
 118
 119     bool volume_writable:1;
 120
 121     bool muted:1;
 122
 123     /* if true then the sink we are connected to and/or the volume
 124      * set is worth remembering, i.e. was explicitly chosen by the
 125      * user and not automatically. module-stream-restore looks for
 126      * this.*/
 127     bool save_sink:1, save_volume:1, save_muted:1;
 128
 129     /* for volume ramps */
 130     pa_cvolume_ramp_int ramp;
 131
 132     pa_resample_method_t requested_resample_method, actual_resample_method;
 133
 134     /* Returns the chunk of audio data and drops it from the
 135      * queue. Returns -1 on failure. Called from IO thread context. If
 136      * data needs to be generated from scratch then please in the
 137      * specified length request_nbytes. This is an optimization
 138      * only. If less data is available, it's fine to return a smaller
 139      * block. If more data is already ready, it is better to return
 140      * the full block. */
 141     int (*pop) (pa_sink_input *i, size_t request_nbytes, pa_memchunk *chunk); /* may NOT be NULL */
 142
 143     /* This is called when the playback buffer has actually played back
 144        all available data. Return true unless there is more data to play back.
 145        Called from IO context. */
 146     bool (*process_underrun) (pa_sink_input *i);
 147
 148     /* Rewind the queue by the specified number of bytes. Called just
 149      * before peek() if it is called at all. Only called if the sink
 150      * input driver ever plans to call
 151      * pa_sink_input_request_rewind(). Called from IO context. */
 152     void (*process_rewind) (pa_sink_input *i, size_t nbytes);     /* may NOT be NULL */
 153
 154     /* Called whenever the maximum rewindable size of the sink
 155      * changes. Called from IO context. */
 156     void (*update_max_rewind) (pa_sink_input *i, size_t nbytes); /* may be NULL */
 157
 158     /* Called whenever the maximum request size of the sink
 159      * changes. Called from IO context. */
 160     void (*update_max_request) (pa_sink_input *i, size_t nbytes); /* may be NULL */
 161
 162     /* Called whenever the configured latency of the sink
 163      * changes. Called from IO context. */
 164     void (*update_sink_requested_latency) (pa_sink_input *i); /* may be NULL */
 165
 166     /* Called whenever the latency range of the sink changes. Called
 167      * from IO context. */
 168     void (*update_sink_latency_range) (pa_sink_input *i); /* may be NULL */
 169
 170     /* Called whenever the fixed latency of the sink changes, if there
 171      * is one. Called from IO context. */
 172     void (*update_sink_fixed_latency) (pa_sink_input *i); /* may be NULL */
 173
 174     /* If non-NULL this function is called when the input is first
 175      * connected to a sink or when the rtpoll/asyncmsgq fields
 176      * change. You usually don't need to implement this function
 177      * unless you rewrite a sink that is piggy-backed onto
 178      * another. Called from IO thread context */
 179     void (*attach) (pa_sink_input *i);           /* may be NULL */
 180
 181     /* If non-NULL this function is called when the output is
 182      * disconnected from its sink. Called from IO thread context */
 183     void (*detach) (pa_sink_input *i);           /* may be NULL */
 184
 185     /* If non-NULL called whenever the sink this input is attached
 186      * to suspends or resumes. Called from main context */
 187     void (*suspend) (pa_sink_input *i, bool b);   /* may be NULL */
 188
 189     /* If non-NULL called whenever the sink this input is attached
 190      * to suspends or resumes. Called from IO context */
 191     void (*suspend_within_thread) (pa_sink_input *i, bool b);   /* may be NULL */
 192
 193     /* If non-NULL called whenever the sink input is moved to a new
 194      * sink. Called from main context after the sink input has been
 195      * detached from the old sink and before it has been attached to
 196      * the new sink. If dest is NULL the move was executed in two
 197      * phases and the second one failed; the stream will be destroyed
 198      * after this call. */
 199     void (*moving) (pa_sink_input *i, pa_sink *dest);   /* may be NULL */
 200
 201     /* Supposed to unlink and destroy this stream. Called from main
 202      * context. */
 203     void (*kill) (pa_sink_input *i);             /* may NOT be NULL */
 204
 205     /* Return the current latency (i.e. length of buffered audio) of
 206     this stream. Called from main context. This is added to what the
 207     PA_SINK_INPUT_MESSAGE_GET_LATENCY message sent to the IO thread
 208     returns */
 209     pa_usec_t (*get_latency) (pa_sink_input *i); /* may be NULL */
 210
 211     /* If non-NULL this function is called from thread context if the
 212      * state changes. The old state is found in thread_info.state.  */
 213     void (*state_change) (pa_sink_input *i, pa_sink_input_state_t state); /* may be NULL */
 214
 215     /* If non-NULL this function is called before this sink input is
 216      * move to a sink and if it returns false the move will not
 217      * be allowed */
 218     bool (*may_move_to) (pa_sink_input *i, pa_sink *s); /* may be NULL */
 219
 220     /* If non-NULL this function is used to dispatch asynchronous
 221      * control events. Called from main context. */
 222     void (*send_event)(pa_sink_input *i, const char *event, pa_proplist* data); /* may be NULL */
 223
 224     /* If non-NULL this function is called whenever the sink input
 225      * volume changes. Called from main context */
 226     void (*volume_changed)(pa_sink_input *i); /* may be NULL */
 227
 228     /* If non-NULL this function is called whenever the sink input
 229      * mute status changes. Called from main context */
 230     void (*mute_changed)(pa_sink_input *i); /* may be NULL */
 231
 232     struct {
 233         pa_sink_input_state_t state;
 234         pa_atomic_t drained;
 235
 236         pa_cvolume soft_volume;
 237         bool muted:1;
 238
 239         bool attached:1; /* True only between ->attach() and ->detach() calls */
 240
 241         /* rewrite_nbytes: 0: rewrite nothing, (size_t) -1: rewrite everything, otherwise how many bytes to rewrite */
 242         bool rewrite_flush:1, dont_rewind_render:1;
 243         size_t rewrite_nbytes;
 244         uint64_t underrun_for, playing_for;
 245         uint64_t underrun_for_sink; /* Like underrun_for, but in sink sample spec */
 246
 247         pa_sample_spec sample_spec;
 248
 249         pa_resampler *resampler;                     /* may be NULL */
 250
 251         /* We maintain a history of resampled audio data here. */
 252         pa_memblockq *render_memblockq;
 253
 254         pa_sink_input *sync_prev, *sync_next;
 255
 256         /* The requested latency for the sink */
 257         pa_usec_t requested_sink_latency;
 258
 259         pa_hashmap *direct_outputs;
 260
 261         pa_cvolume_ramp_int ramp;
 262     } thread_info;
 263
 264     void *userdata;
 265 };
 266
 267 PA_DECLARE_PUBLIC_CLASS(pa_sink_input);
 268 #define PA_SINK_INPUT(o) pa_sink_input_cast(o)
 269
 270 enum {
 271     PA_SINK_INPUT_MESSAGE_SET_SOFT_VOLUME,
 272     PA_SINK_INPUT_MESSAGE_SET_SOFT_MUTE,
 273     PA_SINK_INPUT_MESSAGE_GET_LATENCY,
 274     PA_SINK_INPUT_MESSAGE_SET_RATE,
 275     PA_SINK_INPUT_MESSAGE_SET_STATE,
 276     PA_SINK_INPUT_MESSAGE_SET_REQUESTED_LATENCY,
 277     PA_SINK_INPUT_MESSAGE_GET_REQUESTED_LATENCY,
 278     PA_SINK_INPUT_MESSAGE_SET_VOLUME_RAMP,
 279     PA_SINK_INPUT_MESSAGE_MAX
 280 };
 281
 282 typedef struct pa_sink_input_send_event_hook_data {
 283     pa_sink_input *sink_input;
 284     const char *event;
 285     pa_proplist *data;
 286 } pa_sink_input_send_event_hook_data;
 287
 288 typedef struct pa_sink_input_new_data {
 289     pa_sink_input_flags_t flags;
 290
 291     pa_proplist *proplist;
 292
 293     const char *driver;
 294     pa_module *module;
 295     pa_client *client;
 296
 297     pa_sink *sink;
 298     pa_sink *origin_sink;
 299
 300     pa_resample_method_t resample_method;
 301
 302     pa_sink_input *sync_base;
 303
 304     pa_sample_spec sample_spec;
 305     pa_channel_map channel_map;
 306     pa_format_info *format;
 307     pa_idxset *req_formats;
 308     pa_idxset *nego_formats;
 309
 310     pa_cvolume volume;
 311     bool muted:1;
 312     pa_hashmap *volume_factor_items, *volume_factor_sink_items;
 313
 314     bool sample_spec_is_set:1;
 315     bool channel_map_is_set:1;
 316
 317     bool volume_is_set:1;
 318     bool muted_is_set:1;
 319
 320     bool volume_is_absolute:1;
 321
 322     bool volume_writable:1;
 323
 324     bool save_sink:1, save_volume:1, save_muted:1;
 325 } pa_sink_input_new_data;
 326
 327 pa_sink_input_new_data* pa_sink_input_new_data_init(pa_sink_input_new_data *data);
 328 void pa_sink_input_new_data_set_sample_spec(pa_sink_input_new_data *data, const pa_sample_spec *spec);
 329 void pa_sink_input_new_data_set_channel_map(pa_sink_input_new_data *data, const pa_channel_map *map);
 330 bool pa_sink_input_new_data_is_passthrough(pa_sink_input_new_data *data);
 331 void pa_sink_input_new_data_set_volume(pa_sink_input_new_data *data, const pa_cvolume *volume);
 332 void pa_sink_input_new_data_add_volume_factor(pa_sink_input_new_data *data, const char *key, const pa_cvolume *volume_factor);
 333 void pa_sink_input_new_data_add_volume_factor_sink(pa_sink_input_new_data *data, const char *key, const pa_cvolume *volume_factor);
 334 void pa_sink_input_new_data_set_muted(pa_sink_input_new_data *data, bool mute);
 335 bool pa_sink_input_new_data_set_sink(pa_sink_input_new_data *data, pa_sink *s, bool save);
 336 bool pa_sink_input_new_data_set_formats(pa_sink_input_new_data *data, pa_idxset *formats);
 337 void pa_sink_input_new_data_done(pa_sink_input_new_data *data);
 338
 339 /* To be called by the implementing module only */
 340
 341 int pa_sink_input_new(
 342         pa_sink_input **i,
 343         pa_core *core,
 344         pa_sink_input_new_data *data);
 345
 346 void pa_sink_input_put(pa_sink_input *i);
 347 void pa_sink_input_unlink(pa_sink_input* i);
 348
 349 void pa_sink_input_set_name(pa_sink_input *i, const char *name);
 350
 351 pa_usec_t pa_sink_input_set_requested_latency(pa_sink_input *i, pa_usec_t usec);
 352
 353 /* Request that the specified number of bytes already written out to
 354 the hw device is rewritten, if possible.  Please note that this is
 355 only a kind request. The sink driver may not be able to fulfill it
 356 fully -- or at all. If the request for a rewrite was successful, the
 357 sink driver will call ->rewind() and pass the number of bytes that
 358 could be rewound in the HW device. This functionality is required for
 359 implementing the "zero latency" write-through functionality. */
 360 void pa_sink_input_request_rewind(pa_sink_input *i, size_t nbytes, bool rewrite, bool flush, bool dont_rewind_render);
 361
 362 void pa_sink_input_cork(pa_sink_input *i, bool b);
 363
 364 int pa_sink_input_set_rate(pa_sink_input *i, uint32_t rate);
 365 int pa_sink_input_update_rate(pa_sink_input *i);
 366
 367 /* This returns the sink's fields converted into out sample type */
 368 size_t pa_sink_input_get_max_rewind(pa_sink_input *i);
 369 size_t pa_sink_input_get_max_request(pa_sink_input *i);
 370
 371 /* Callable by everyone from main thread*/
 372
 373 /* External code may request disconnection with this function */
 374 void pa_sink_input_kill(pa_sink_input*i);
 375
 376 pa_usec_t pa_sink_input_get_latency(pa_sink_input *i, pa_usec_t *sink_latency);
 377
 378 bool pa_sink_input_is_passthrough(pa_sink_input *i);
 379 bool pa_sink_input_is_volume_readable(pa_sink_input *i);
 380 void pa_sink_input_set_volume(pa_sink_input *i, const pa_cvolume *volume, bool save, bool absolute);
 381 void pa_sink_input_add_volume_factor(pa_sink_input *i, const char *key, const pa_cvolume *volume_factor);
 382 int pa_sink_input_remove_volume_factor(pa_sink_input *i, const char *key);
 383 pa_cvolume *pa_sink_input_get_volume(pa_sink_input *i, pa_cvolume *volume, bool absolute);
 384
 385 void pa_sink_input_set_mute(pa_sink_input *i, bool mute, bool save);
 386 bool pa_sink_input_get_mute(pa_sink_input *i);
 387
 388 void pa_sink_input_set_volume_ramp(pa_sink_input *i, const pa_cvolume_ramp *ramp, bool send_msg, bool save);
 389
 390 void pa_sink_input_update_proplist(pa_sink_input *i, pa_update_mode_t mode, pa_proplist *p);
 391
 392 pa_resample_method_t pa_sink_input_get_resample_method(pa_sink_input *i);
 393
 394 void pa_sink_input_send_event(pa_sink_input *i, const char *name, pa_proplist *data);
 395
 396 int pa_sink_input_move_to(pa_sink_input *i, pa_sink *dest, bool save);
 397 bool pa_sink_input_may_move(pa_sink_input *i); /* may this sink input move at all? */
 398 bool pa_sink_input_may_move_to(pa_sink_input *i, pa_sink *dest); /* may this sink input move to this sink? */
 399
 400 /* The same as pa_sink_input_move_to() but in two separate steps,
 401  * first the detaching from the old sink, then the attaching to the
 402  * new sink */
 403 int pa_sink_input_start_move(pa_sink_input *i);
 404 int pa_sink_input_finish_move(pa_sink_input *i, pa_sink *dest, bool save);
 405 void pa_sink_input_fail_move(pa_sink_input *i);
 406
 407 pa_sink_input_state_t pa_sink_input_get_state(pa_sink_input *i);
 408
 409 pa_usec_t pa_sink_input_get_requested_latency(pa_sink_input *i);
 410
 411 /* To be used exclusively by the sink driver IO thread */
 412
 413 void pa_sink_input_peek(pa_sink_input *i, size_t length, pa_memchunk *chunk, pa_cvolume *volume);
 414 void pa_sink_input_drop(pa_sink_input *i, size_t length);
 415 void pa_sink_input_process_rewind(pa_sink_input *i, size_t nbytes /* in the sink's sample spec */);
 416 void pa_sink_input_update_max_rewind(pa_sink_input *i, size_t nbytes  /* in the sink's sample spec */);
 417 void pa_sink_input_update_max_request(pa_sink_input *i, size_t nbytes  /* in the sink's sample spec */);
 418
 419 void pa_sink_input_set_state_within_thread(pa_sink_input *i, pa_sink_input_state_t state);
 420
 421 int pa_sink_input_process_msg(pa_msgobject *o, int code, void *userdata, int64_t offset, pa_memchunk *chunk);
 422
 423 pa_usec_t pa_sink_input_set_requested_latency_within_thread(pa_sink_input *i, pa_usec_t usec);
 424
 425 bool pa_sink_input_safe_to_remove(pa_sink_input *i);
 426 bool pa_sink_input_process_underrun(pa_sink_input *i);
 427
 428 pa_memchunk* pa_sink_input_get_silence(pa_sink_input *i, pa_memchunk *ret);
 429
 430 #define pa_sink_input_assert_io_context(s) \
 431     pa_assert(pa_thread_mq_get() || !PA_SINK_INPUT_IS_LINKED((s)->state))
 432
 433 #endif