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