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