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