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