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