src/pulsecore/source-output.h

   1 #ifndef foopulsesourceoutputhfoo
   2 #define foopulsesourceoutputhfoo
   3
   4 /***
   5   This file is part of PulseAudio.
   6
   7   Copyright 2004-2006 Lennart Poettering
   8
   9   PulseAudio is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU Lesser General Public License as published
  11   by the Free Software Foundation; either version 2.1 of the License,
  12   or (at your option) any later version.
  13
  14   PulseAudio is distributed in the hope that it will be useful, but
  15   WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17   General Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public License
  20   along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
  21 ***/
  22
  23 #include <inttypes.h>
  24
  25 #include <pulsecore/typedefs.h>
  26 #include <pulse/sample.h>
  27 #include <pulse/format.h>
  28 #include <pulsecore/memblockq.h>
  29 #include <pulsecore/resampler.h>
  30 #include <pulsecore/module.h>
  31 #include <pulsecore/client.h>
  32 #include <pulsecore/source.h>
  33 #include <pulsecore/core.h>
  34 #include <pulsecore/sink-input.h>
  35
  36 typedef enum pa_source_output_state {
  37     PA_SOURCE_OUTPUT_INIT,
  38     PA_SOURCE_OUTPUT_RUNNING,
  39     PA_SOURCE_OUTPUT_CORKED,
  40     PA_SOURCE_OUTPUT_UNLINKED
  41 } pa_source_output_state_t;
  42
  43 static inline bool PA_SOURCE_OUTPUT_IS_LINKED(pa_source_output_state_t x) {
  44     return x == PA_SOURCE_OUTPUT_RUNNING || x == PA_SOURCE_OUTPUT_CORKED;
  45 }
  46
  47 typedef enum pa_source_output_flags {
  48     PA_SOURCE_OUTPUT_VARIABLE_RATE = 1,
  49     PA_SOURCE_OUTPUT_DONT_MOVE = 2,
  50     PA_SOURCE_OUTPUT_START_CORKED = 4,
  51     PA_SOURCE_OUTPUT_NO_REMAP = 8,
  52     PA_SOURCE_OUTPUT_NO_REMIX = 16,
  53     PA_SOURCE_OUTPUT_FIX_FORMAT = 32,
  54     PA_SOURCE_OUTPUT_FIX_RATE = 64,
  55     PA_SOURCE_OUTPUT_FIX_CHANNELS = 128,
  56     PA_SOURCE_OUTPUT_DONT_INHIBIT_AUTO_SUSPEND = 256,
  57     PA_SOURCE_OUTPUT_NO_CREATE_ON_SUSPEND = 512,
  58     PA_SOURCE_OUTPUT_KILL_ON_SUSPEND = 1024,
  59     PA_SOURCE_OUTPUT_PASSTHROUGH = 2048,
  60 #ifdef __TIZEN__
  61     PA_SOURCE_OUTPUT_PREPROCESSOR = 4096,
  62 #endif
  63 } pa_source_output_flags_t;
  64
  65 struct pa_source_output {
  66     pa_msgobject parent;
  67
  68     uint32_t index;
  69     pa_core *core;
  70
  71     pa_source_output_state_t state;
  72     pa_source_output_flags_t flags;
  73
  74     char *driver;                         /* may be NULL */
  75     pa_proplist *proplist;
  76
  77     pa_module *module;                    /* may be NULL */
  78     pa_client *client;                    /* may be NULL */
  79
  80     pa_source *source;                    /* NULL while being moved */
  81
  82     /* This is set to true when creating the source output if the source was
  83      * requested by the application that created the source output. This is
  84      * sometimes useful for determining whether the source output should be
  85      * moved by some automatic policy. If the source output is moved away from
  86      * the source that the application requested, this flag is reset to
  87      * false. */
  88     bool source_requested_by_application;
  89
  90     pa_source *destination_source;        /* only set by filter sources */
  91
  92     /* A source output can monitor just a single input of a sink, in which case we find it here */
  93     pa_sink_input *direct_on_input;       /* may be NULL */
  94
  95     pa_sample_spec sample_spec;
  96     pa_channel_map channel_map;
  97     pa_format_info *format;
  98
  99     /* Also see http://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/Developer/Volumes/ */
 100     pa_cvolume volume;             /* The volume clients are informed about */
 101     pa_cvolume reference_ratio;    /* The ratio of the stream's volume to the source's reference volume */
 102     pa_cvolume real_ratio;         /* The ratio of the stream's volume to the source'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_source; /* A second volume factor in format of the source this stream is connected to */
 107
 108 #ifdef __TIZEN__
 109     double individual_volume_ratio;         /* The ratio of the stream's volume to the value of its volume group. */
 110 #endif
 111     bool volume_writable:1;
 112
 113     bool muted:1;
 114
 115     /* if true then the volume and the mute state of this source-output
 116      * are worth remembering, module-stream-restore looks for this. */
 117     bool save_volume:1, save_muted:1;
 118
 119     /* if users move the source-output to a source, and the source is not
 120      * default_source, the source->name will be saved in preferred_source. And
 121      * later if source-output is moved to other sources for some reason, it
 122      * still can be restored to the preferred_source at an appropriate time */
 123     char *preferred_source;
 124
 125     pa_resample_method_t requested_resample_method, actual_resample_method;
 126
 127     /* Pushes a new memchunk into the output. Called from IO thread
 128      * context. */
 129     void (*push)(pa_source_output *o, const pa_memchunk *chunk); /* may NOT be NULL */
 130
 131     /* Only relevant for monitor sources right now: called when the
 132      * recorded stream is rewound. Called from IO context */
 133     void (*process_rewind)(pa_source_output *o, size_t nbytes); /* may be NULL */
 134
 135     /* Called whenever the maximum rewindable size of the source
 136      * changes. Called from IO thread context. */
 137     void (*update_max_rewind) (pa_source_output *o, size_t nbytes); /* may be NULL */
 138
 139     /* Called whenever the configured latency of the source
 140      * changes. Called from IO context. */
 141     void (*update_source_requested_latency) (pa_source_output *o); /* may be NULL */
 142
 143     /* Called whenever the latency range of the source changes. Called
 144      * from IO context. */
 145     void (*update_source_latency_range) (pa_source_output *o); /* may be NULL */
 146
 147     /* Called whenever the fixed latency of the source changes, if there
 148      * is one. Called from IO context. */
 149     void (*update_source_fixed_latency) (pa_source_output *i); /* may be NULL */
 150
 151     /* If non-NULL this function is called when the output is first
 152      * connected to a source or when the rtpoll/asyncmsgq fields
 153      * change. You usually don't need to implement this function
 154      * unless you rewrite a source that is piggy-backed onto
 155      * another. Called from IO thread context */
 156     void (*attach) (pa_source_output *o);           /* may be NULL */
 157
 158     /* If non-NULL this function is called when the output is
 159      * disconnected from its source. Called from IO thread context */
 160     void (*detach) (pa_source_output *o);           /* may be NULL */
 161
 162     /* If non-NULL called whenever the source this output is attached
 163      * to suspends or resumes or if the suspend cause changes.
 164      * Called from main context */
 165     void (*suspend) (pa_source_output *o, pa_source_state_t old_state, pa_suspend_cause_t old_suspend_cause);   /* may be NULL */
 166
 167     /* If non-NULL called whenever the source this output is attached
 168      * to suspends or resumes. Called from IO context */
 169     void (*suspend_within_thread) (pa_source_output *o, bool b);   /* may be NULL */
 170
 171     /* If non-NULL called whenever the source output is moved to a new
 172      * source. Called from main context after the source output has been
 173      * detached from the old source and before it has been attached to
 174      * the new source. If dest is NULL the move was executed in two
 175      * phases and the second one failed; the stream will be destroyed
 176      * after this call. */
 177     void (*moving) (pa_source_output *o, pa_source *dest);   /* may be NULL */
 178
 179     /* Supposed to unlink and destroy this stream. Called from main
 180      * context. */
 181     void (*kill)(pa_source_output* o);              /* may NOT be NULL */
 182
 183     /* Return the current latency (i.e. length of buffered audio) of
 184     this stream. Called from main context. This is added to what the
 185     PA_SOURCE_OUTPUT_MESSAGE_GET_LATENCY message sent to the IO thread
 186     returns */
 187     pa_usec_t (*get_latency) (pa_source_output *o); /* may be NULL */
 188
 189     /* If non-NULL this function is called from thread context if the
 190      * state changes. The old state is found in thread_info.state.  */
 191     void (*state_change) (pa_source_output *o, pa_source_output_state_t state); /* may be NULL */
 192
 193     /* If non-NULL this function is called before this source output
 194      * is moved to a source and if it returns false the move
 195      * will not be allowed */
 196     bool (*may_move_to) (pa_source_output *o, pa_source *s); /* may be NULL */
 197
 198     /* If non-NULL this function is used to dispatch asynchronous
 199      * control events. */
 200     void (*send_event)(pa_source_output *o, const char *event, pa_proplist* data);
 201
 202     /* If non-NULL this function is called whenever the source output
 203      * volume changes. Called from main context */
 204     void (*volume_changed)(pa_source_output *o); /* may be NULL */
 205
 206     /* If non-NULL this function is called whenever the source output
 207      * mute status changes. Called from main context */
 208     void (*mute_changed)(pa_source_output *o); /* may be NULL */
 209
 210 #ifdef __TIZEN__
 211     int (*preprocess)(pa_source_output *o, pa_memchunk *chunk, pa_memchunk *ochunk);
 212 #endif
 213
 214     struct {
 215         pa_source_output_state_t state;
 216
 217         pa_cvolume soft_volume;
 218         bool muted:1;
 219
 220         bool attached:1; /* True only between ->attach() and ->detach() calls */
 221
 222         pa_sample_spec sample_spec;
 223
 224         pa_resampler* resampler;              /* may be NULL */
 225
 226         /* We maintain a delay memblockq here for source outputs that
 227          * don't implement rewind() */
 228         pa_memblockq *delay_memblockq;
 229
 230         /* The requested latency for the source */
 231         pa_usec_t requested_source_latency;
 232
 233         pa_sink_input *direct_on_input;       /* may be NULL */
 234
 235 #ifdef __TIZEN__
 236         void *processor_holder;
 237 #endif
 238     } thread_info;
 239 #ifdef __TIZEN__
 240     pa_usec_t time_of_start_to_run;
 241     FILE *pcm_dump_fp;
 242     char *dump_path;
 243 #endif
 244
 245     void *userdata;
 246 };
 247
 248 PA_DECLARE_PUBLIC_CLASS(pa_source_output);
 249 #define PA_SOURCE_OUTPUT(o) pa_source_output_cast(o)
 250
 251 enum {
 252     PA_SOURCE_OUTPUT_MESSAGE_GET_LATENCY,
 253     PA_SOURCE_OUTPUT_MESSAGE_SET_RATE,
 254     PA_SOURCE_OUTPUT_MESSAGE_SET_STATE,
 255     PA_SOURCE_OUTPUT_MESSAGE_SET_REQUESTED_LATENCY,
 256     PA_SOURCE_OUTPUT_MESSAGE_GET_REQUESTED_LATENCY,
 257     PA_SOURCE_OUTPUT_MESSAGE_SET_SOFT_VOLUME,
 258     PA_SOURCE_OUTPUT_MESSAGE_SET_SOFT_MUTE,
 259     PA_SOURCE_OUTPUT_MESSAGE_MAX
 260 };
 261
 262 typedef struct pa_source_output_send_event_hook_data {
 263     pa_source_output *source_output;
 264     const char *event;
 265     pa_proplist *data;
 266 } pa_source_output_send_event_hook_data;
 267
 268 typedef struct pa_source_output_new_data {
 269     pa_source_output_flags_t flags;
 270
 271     pa_proplist *proplist;
 272     pa_sink_input *direct_on_input;
 273
 274     const char *driver;
 275     pa_module *module;
 276     pa_client *client;
 277
 278     pa_source *source;
 279     bool source_requested_by_application;
 280     pa_source *destination_source;
 281
 282     pa_resample_method_t resample_method;
 283
 284     pa_sample_spec sample_spec;
 285     pa_channel_map channel_map;
 286     pa_format_info *format;
 287     pa_idxset *req_formats;
 288     pa_idxset *nego_formats;
 289
 290     pa_cvolume volume, volume_factor, volume_factor_source;
 291 #ifdef __TIZEN__
 292     double individual_volume_ratio;
 293     void *processor_holder;
 294 #endif
 295     bool muted:1;
 296
 297     bool sample_spec_is_set:1;
 298     bool channel_map_is_set:1;
 299
 300     bool volume_is_set:1, volume_factor_is_set:1, volume_factor_source_is_set:1;
 301     bool muted_is_set:1;
 302
 303     bool volume_is_absolute:1;
 304
 305     bool volume_writable:1;
 306
 307     bool save_volume:1, save_muted:1;
 308     char *preferred_source;
 309 } pa_source_output_new_data;
 310
 311 pa_source_output_new_data* pa_source_output_new_data_init(pa_source_output_new_data *data);
 312 void pa_source_output_new_data_set_sample_spec(pa_source_output_new_data *data, const pa_sample_spec *spec);
 313 void pa_source_output_new_data_set_channel_map(pa_source_output_new_data *data, const pa_channel_map *map);
 314 bool pa_source_output_new_data_is_passthrough(pa_source_output_new_data *data);
 315 void pa_source_output_new_data_set_volume(pa_source_output_new_data *data, const pa_cvolume *volume);
 316 void pa_source_output_new_data_apply_volume_factor(pa_source_output_new_data *data, const pa_cvolume *volume_factor);
 317 void pa_source_output_new_data_apply_volume_factor_source(pa_source_output_new_data *data, const pa_cvolume *volume_factor);
 318 void pa_source_output_new_data_set_muted(pa_source_output_new_data *data, bool mute);
 319 bool pa_source_output_new_data_set_source(pa_source_output_new_data *data, pa_source *s, bool save,
 320                                           bool requested_by_application);
 321 bool pa_source_output_new_data_set_formats(pa_source_output_new_data *data, pa_idxset *formats);
 322 void pa_source_output_new_data_done(pa_source_output_new_data *data);
 323
 324 /* To be called by the implementing module only */
 325
 326 int pa_source_output_new(
 327         pa_source_output**o,
 328         pa_core *core,
 329         pa_source_output_new_data *data);
 330
 331 void pa_source_output_put(pa_source_output *o);
 332 void pa_source_output_unlink(pa_source_output*o);
 333
 334 pa_usec_t pa_source_output_set_requested_latency(pa_source_output *o, pa_usec_t usec);
 335
 336 void pa_source_output_cork(pa_source_output *o, bool b);
 337
 338 int pa_source_output_set_rate(pa_source_output *o, uint32_t rate);
 339 int pa_source_output_update_resampler(pa_source_output *o);
 340
 341 size_t pa_source_output_get_max_rewind(pa_source_output *o);
 342
 343 /* Callable by everyone */
 344
 345 /* External code may request disconnection with this function */
 346 void pa_source_output_kill(pa_source_output*o);
 347
 348 pa_usec_t pa_source_output_get_latency(pa_source_output *o, pa_usec_t *source_latency);
 349
 350 bool pa_source_output_is_volume_readable(pa_source_output *o);
 351 bool pa_source_output_is_passthrough(pa_source_output *o);
 352 void pa_source_output_set_volume(pa_source_output *o, const pa_cvolume *volume, bool save, bool absolute);
 353 pa_cvolume *pa_source_output_get_volume(pa_source_output *o, pa_cvolume *volume, bool absolute);
 354
 355 void pa_source_output_set_mute(pa_source_output *o, bool mute, bool save);
 356
 357 void pa_source_output_set_property(pa_source_output *o, const char *key, const char *value);
 358 void pa_source_output_set_property_arbitrary(pa_source_output *o, const char *key, const uint8_t *value, size_t nbytes);
 359 void pa_source_output_update_proplist(pa_source_output *o, pa_update_mode_t mode, pa_proplist *p);
 360
 361 pa_resample_method_t pa_source_output_get_resample_method(pa_source_output *o);
 362
 363 void pa_source_output_send_event(pa_source_output *o, const char *name, pa_proplist *data);
 364
 365 bool pa_source_output_may_move(pa_source_output *o);
 366 bool pa_source_output_may_move_to(pa_source_output *o, pa_source *dest);
 367 int pa_source_output_move_to(pa_source_output *o, pa_source *dest, bool save);
 368
 369 /* The same as pa_source_output_move_to() but in two separate steps,
 370  * first the detaching from the old source, then the attaching to the
 371  * new source */
 372 int pa_source_output_start_move(pa_source_output *o);
 373 int pa_source_output_finish_move(pa_source_output *o, pa_source *dest, bool save);
 374 void pa_source_output_fail_move(pa_source_output *o);
 375
 376 pa_usec_t pa_source_output_get_requested_latency(pa_source_output *o);
 377
 378 /* To be used exclusively by the source driver thread */
 379
 380 void pa_source_output_push(pa_source_output *o, const pa_memchunk *chunk);
 381 void pa_source_output_process_rewind(pa_source_output *o, size_t nbytes);
 382 void pa_source_output_update_max_rewind(pa_source_output *o, size_t nbytes);
 383
 384 void pa_source_output_set_state_within_thread(pa_source_output *o, pa_source_output_state_t state);
 385
 386 int pa_source_output_process_msg(pa_msgobject *mo, int code, void *userdata, int64_t offset, pa_memchunk *chunk);
 387
 388 pa_usec_t pa_source_output_set_requested_latency_within_thread(pa_source_output *o, pa_usec_t usec);
 389
 390 /* Calls the attach() callback if it's set. The output must be in detached
 391  * state. */
 392 void pa_source_output_attach(pa_source_output *o);
 393
 394 /* Calls the detach() callback if it's set and the output is attached. The
 395  * output is allowed to be already detached, in which case this does nothing.
 396  *
 397  * The reason why this can be called for already-detached outputs is that when
 398  * a filter source's output is detached, it has to detach also all outputs
 399  * connected to the filter source. In case the filter source's output was
 400  * detached because the filter source is being removed, those other outputs
 401  * will be moved to another source or removed, and moving and removing involve
 402  * detaching the outputs, but the outputs at that point are already detached.
 403  *
 404  * XXX: Moving or removing an output also involves sending messages to the
 405  * output's source. If the output's source is a detached filter source,
 406  * shouldn't sending messages to it be prohibited? The messages are processed
 407  * in the root source's IO thread, and when the filter source is detached, it
 408  * would seem logical to prohibit any interaction with the IO thread that isn't
 409  * any more associated with the filter source. Currently sending messages to
 410  * detached filter sources mostly works, because the filter sources don't
 411  * update their asyncmsgq pointer when detaching, so messages still find their
 412  * way to the old IO thread. */
 413 void pa_source_output_detach(pa_source_output *o);
 414
 415 /* Called from the main thread, from source.c only. The normal way to set the
 416  * source output volume is to call pa_source_output_set_volume(), but the flat
 417  * volume logic in source.c needs also a function that doesn't do all the extra
 418  * stuff that pa_source_output_set_volume() does. This function simply sets
 419  * o->volume and fires change notifications. */
 420 void pa_source_output_set_volume_direct(pa_source_output *o, const pa_cvolume *volume);
 421
 422 /* Called from the main thread, from source.c only. This shouldn't be a public
 423  * function, but the flat volume logic in source.c currently needs a way to
 424  * directly set the source output reference ratio. This function simply sets
 425  * o->reference_ratio and logs a message if the value changes. */
 426 void pa_source_output_set_reference_ratio(pa_source_output *o, const pa_cvolume *ratio);
 427
 428 void pa_source_output_set_preferred_source(pa_source_output *o, pa_source *s);
 429
 430 #ifdef __TIZEN__
 431 void pa_source_output_dump_info(pa_source_output *o, unsigned int iteration, unsigned int total);
 432 #endif
 433
 434 #define pa_source_output_assert_io_context(s) \
 435     pa_assert(pa_thread_mq_get() || !PA_SOURCE_OUTPUT_IS_LINKED((s)->state))
 436
 437 #endif