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, see <http://www.gnu.org/licenses/>.
22 ***/
23
24 #include <inttypes.h>
25
26 #include <pulsecore/typedefs.h>
27 #include <pulse/sample.h>
28 #include <pulse/format.h>
29 #include <pulsecore/memblockq.h>
30 #include <pulsecore/resampler.h>
31 #include <pulsecore/module.h>
32 #include <pulsecore/client.h>
33 #include <pulsecore/sink.h>
34 #include <pulsecore/core.h>
35
36 typedef enum pa_sink_input_state {
37 PA_SINK_INPUT_INIT, /*< The stream is not active yet, because pa_sink_input_put() has not been called yet */
38 PA_SINK_INPUT_RUNNING, /*< The stream is alive and kicking */
39 PA_SINK_INPUT_CORKED, /*< The stream was corked on user request */
40 PA_SINK_INPUT_UNLINKED /*< The stream is dead */
41 /* FIXME: we need a state for MOVING here */
42 } pa_sink_input_state_t;
43
PA_SINK_INPUT_IS_LINKED(pa_sink_input_state_t x)44 static inline bool PA_SINK_INPUT_IS_LINKED(pa_sink_input_state_t x) {
45 return x == PA_SINK_INPUT_RUNNING || x == PA_SINK_INPUT_CORKED;
46 }
47
48 typedef enum pa_sink_input_flags {
49 PA_SINK_INPUT_VARIABLE_RATE = 1,
50 PA_SINK_INPUT_DONT_MOVE = 2,
51 PA_SINK_INPUT_START_CORKED = 4,
52 PA_SINK_INPUT_NO_REMAP = 8,
53 PA_SINK_INPUT_NO_REMIX = 16,
54 PA_SINK_INPUT_FIX_FORMAT = 32,
55 PA_SINK_INPUT_FIX_RATE = 64,
56 PA_SINK_INPUT_FIX_CHANNELS = 128,
57 PA_SINK_INPUT_DONT_INHIBIT_AUTO_SUSPEND = 256,
58 PA_SINK_INPUT_NO_CREATE_ON_SUSPEND = 512,
59 PA_SINK_INPUT_KILL_ON_SUSPEND = 1024,
60 PA_SINK_INPUT_PASSTHROUGH = 2048
61 } pa_sink_input_flags_t;
62
63 struct pa_sink_input {
64 pa_msgobject parent;
65
66 uint32_t index;
67 pa_core *core;
68
69 pa_sink_input_state_t state;
70 pa_sink_input_flags_t flags;
71
72 char *driver; /* may be NULL */
73 pa_proplist *proplist;
74
75 pa_module *module; /* may be NULL */
76 pa_client *client; /* may be NULL */
77
78 pa_sink *sink; /* NULL while we are being moved */
79
80 /* This is set to true when creating the sink input if the sink was
81 * requested by the application that created the sink input. This is
82 * sometimes useful for determining whether the sink input should be
83 * moved by some automatic policy. If the sink input is moved away from the
84 * sink that the application requested, this flag is reset to false. */
85 bool sink_requested_by_application;
86
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://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/Developer/Volumes/ */
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 /* volume_factor is an internally used "additional volume" that can be used
105 * by modules without having the volume visible to clients. volume_factor
106 * calculated by merging all the individual items in volume_factor_items.
107 * Modules must not modify these variables directly, instead
108 * pa_sink_input_add/remove_volume_factor() have to be used to add and
109 * remove items, or pa_sink_input_new_data_add_volume_factor() during input
110 * creation time. */
111 pa_cvolume volume_factor;
112 pa_hashmap *volume_factor_items;
113 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 */
114
115 pa_cvolume volume_factor_sink; /* A second volume factor in format of the sink this stream is connected to. */
116 pa_hashmap *volume_factor_sink_items;
117
118 bool volume_writable:1;
119
120 bool muted:1;
121
122 /* if true then the volume and the mute state of this sink-input
123 * are worth remembering, module-stream-restore looks for
124 * this.*/
125 bool save_volume:1, save_muted:1;
126
127 /* if users move the sink-input to a sink, and the sink is not default_sink,
128 * the sink->name will be saved in preferred_sink. And later if sink-input
129 * is moved to other sinks for some reason, it still can be restored to the
130 * preferred_sink at an appropriate time */
131 char *preferred_sink;
132
133 pa_resample_method_t requested_resample_method, actual_resample_method;
134
135 /* Returns the chunk of audio data and drops it from the
136 * queue. Returns -1 on failure. Called from IO thread context. If
137 * data needs to be generated from scratch then please in the
138 * specified length request_nbytes. This is an optimization
139 * only. If less data is available, it's fine to return a smaller
140 * block. If more data is already ready, it is better to return
141 * the full block. */
142 int (*pop) (pa_sink_input *i, size_t request_nbytes, pa_memchunk *chunk); /* may NOT be NULL */
143
144 /* This is called when the playback buffer has actually played back
145 all available data. Return true unless there is more data to play back.
146 Called from IO context. */
147 bool (*process_underrun) (pa_sink_input *i);
148
149 /* Rewind the queue by the specified number of bytes. Called just
150 * before peek() if it is called at all. Only called if the sink
151 * input driver ever plans to call
152 * pa_sink_input_request_rewind(). Called from IO context. */
153 void (*process_rewind) (pa_sink_input *i, size_t nbytes); /* may NOT be NULL */
154
155 /* Called whenever the maximum rewindable size of the sink
156 * changes. Called from IO context. */
157 void (*update_max_rewind) (pa_sink_input *i, size_t nbytes); /* may be NULL */
158
159 /* Called whenever the maximum request size of the sink
160 * changes. Called from IO context. */
161 void (*update_max_request) (pa_sink_input *i, size_t nbytes); /* may be NULL */
162
163 /* Called whenever the configured latency of the sink
164 * changes. Called from IO context. */
165 void (*update_sink_requested_latency) (pa_sink_input *i); /* may be NULL */
166
167 /* Called whenever the latency range of the sink changes. Called
168 * from IO context. */
169 void (*update_sink_latency_range) (pa_sink_input *i); /* may be NULL */
170
171 /* Called whenever the fixed latency of the sink changes, if there
172 * is one. Called from IO context. */
173 void (*update_sink_fixed_latency) (pa_sink_input *i); /* may be NULL */
174
175 /* If non-NULL this function is called when the input is first
176 * connected to a sink or when the rtpoll/asyncmsgq fields
177 * change. You usually don't need to implement this function
178 * unless you rewrite a sink that is piggy-backed onto
179 * another. Called from IO thread context */
180 void (*attach) (pa_sink_input *i); /* may be NULL */
181
182 /* If non-NULL this function is called when the output is
183 * disconnected from its sink. Called from IO thread context */
184 void (*detach) (pa_sink_input *i); /* may be NULL */
185
186 /* If non-NULL called whenever the sink this input is attached
187 * to suspends or resumes or if the suspend cause changes.
188 * Called from main context */
189 void (*suspend) (pa_sink_input *i, pa_sink_state_t old_state, pa_suspend_cause_t old_suspend_cause); /* may be NULL */
190
191 /* If non-NULL called whenever the sink this input is attached
192 * to suspends or resumes. Called from IO context */
193 void (*suspend_within_thread) (pa_sink_input *i, bool b); /* may be NULL */
194
195 /* If non-NULL called whenever the sink input is moved to a new
196 * sink. Called from main context after the sink input has been
197 * detached from the old sink and before it has been attached to
198 * the new sink. If dest is NULL the move was executed in two
199 * phases and the second one failed; the stream will be destroyed
200 * after this call. */
201 void (*moving) (pa_sink_input *i, pa_sink *dest); /* may be NULL */
202
203 /* Supposed to unlink and destroy this stream. Called from main
204 * context. */
205 void (*kill) (pa_sink_input *i); /* may NOT be NULL */
206
207 /* Return the current latency (i.e. length of buffered audio) of
208 this stream. Called from main context. This is added to what the
209 PA_SINK_INPUT_MESSAGE_GET_LATENCY message sent to the IO thread
210 returns */
211 pa_usec_t (*get_latency) (pa_sink_input *i); /* may be NULL */
212
213 /* If non-NULL this function is called from thread context if the
214 * state changes. The old state is found in thread_info.state. */
215 void (*state_change) (pa_sink_input *i, pa_sink_input_state_t state); /* may be NULL */
216
217 /* If non-NULL this function is called before this sink input is
218 * move to a sink and if it returns false the move will not
219 * be allowed */
220 bool (*may_move_to) (pa_sink_input *i, pa_sink *s); /* may be NULL */
221
222 /* If non-NULL this function is used to dispatch asynchronous
223 * control events. Called from main context. */
224 void (*send_event)(pa_sink_input *i, const char *event, pa_proplist* data); /* may be NULL */
225
226 /* If non-NULL this function is called whenever the sink input
227 * volume changes. Called from main context */
228 void (*volume_changed)(pa_sink_input *i); /* may be NULL */
229
230 /* If non-NULL this function is called whenever the sink input
231 * mute status changes. Called from main context */
232 void (*mute_changed)(pa_sink_input *i); /* may be NULL */
233
234 struct {
235 pa_sink_input_state_t state;
236
237 pa_cvolume soft_volume;
238 bool muted:1;
239
240 bool attached:1; /* True only between ->attach() and ->detach() calls */
241
242 /* rewrite_nbytes: 0: rewrite nothing, (size_t) -1: rewrite everything, otherwise how many bytes to rewrite */
243 bool rewrite_flush:1, dont_rewind_render:1;
244 size_t rewrite_nbytes;
245 uint64_t underrun_for, playing_for;
246 uint64_t underrun_for_sink; /* Like underrun_for, but in sink sample spec */
247
248 pa_sample_spec sample_spec;
249
250 pa_resampler *resampler; /* may be NULL */
251
252 /* We maintain a history of resampled audio data here. */
253 pa_memblockq *render_memblockq;
254
255 pa_sink_input *sync_prev, *sync_next;
256
257 /* The requested latency for the sink */
258 pa_usec_t requested_sink_latency;
259
260 pa_hashmap *direct_outputs;
261 } thread_info;
262
263 void *userdata;
264 };
265
266 PA_DECLARE_PUBLIC_CLASS(pa_sink_input);
267 #define PA_SINK_INPUT(o) pa_sink_input_cast(o)
268
269 enum {
270 PA_SINK_INPUT_MESSAGE_SET_SOFT_VOLUME,
271 PA_SINK_INPUT_MESSAGE_SET_SOFT_MUTE,
272 PA_SINK_INPUT_MESSAGE_GET_LATENCY,
273 PA_SINK_INPUT_MESSAGE_SET_RATE,
274 PA_SINK_INPUT_MESSAGE_SET_STATE,
275 PA_SINK_INPUT_MESSAGE_SET_REQUESTED_LATENCY,
276 PA_SINK_INPUT_MESSAGE_GET_REQUESTED_LATENCY,
277 PA_SINK_INPUT_MESSAGE_MAX
278 };
279
280 typedef struct pa_sink_input_send_event_hook_data {
281 pa_sink_input *sink_input;
282 const char *event;
283 pa_proplist *data;
284 } pa_sink_input_send_event_hook_data;
285
286 typedef struct pa_sink_input_new_data {
287 pa_sink_input_flags_t flags;
288
289 pa_proplist *proplist;
290
291 const char *driver;
292 pa_module *module;
293 pa_client *client;
294
295 pa_sink *sink;
296 bool sink_requested_by_application;
297 pa_sink *origin_sink;
298
299 pa_resample_method_t resample_method;
300
301 pa_sink_input *sync_base;
302
303 pa_sample_spec sample_spec;
304 pa_channel_map channel_map;
305 pa_format_info *format;
306 pa_idxset *req_formats;
307 pa_idxset *nego_formats;
308
309 pa_cvolume volume;
310 bool muted:1;
311 pa_hashmap *volume_factor_items, *volume_factor_sink_items;
312
313 bool sample_spec_is_set:1;
314 bool channel_map_is_set:1;
315
316 bool volume_is_set:1;
317 bool muted_is_set:1;
318
319 bool volume_is_absolute:1;
320
321 bool volume_writable:1;
322
323 bool save_volume:1, save_muted:1;
324
325 char *preferred_sink;
326 } pa_sink_input_new_data;
327
328 pa_sink_input_new_data* pa_sink_input_new_data_init(pa_sink_input_new_data *data);
329 void pa_sink_input_new_data_set_sample_spec(pa_sink_input_new_data *data, const pa_sample_spec *spec);
330 void pa_sink_input_new_data_set_channel_map(pa_sink_input_new_data *data, const pa_channel_map *map);
331 bool pa_sink_input_new_data_is_passthrough(pa_sink_input_new_data *data);
332 void pa_sink_input_new_data_set_volume(pa_sink_input_new_data *data, const pa_cvolume *volume);
333 void pa_sink_input_new_data_add_volume_factor(pa_sink_input_new_data *data, const char *key, const pa_cvolume *volume_factor);
334 void pa_sink_input_new_data_add_volume_factor_sink(pa_sink_input_new_data *data, const char *key, const pa_cvolume *volume_factor);
335 void pa_sink_input_new_data_set_muted(pa_sink_input_new_data *data, bool mute);
336 bool pa_sink_input_new_data_set_sink(pa_sink_input_new_data *data, pa_sink *s, bool save, bool requested_by_application);
337 bool pa_sink_input_new_data_set_formats(pa_sink_input_new_data *data, pa_idxset *formats);
338 void pa_sink_input_new_data_done(pa_sink_input_new_data *data);
339
340 /* To be called by the implementing module only */
341
342 int pa_sink_input_new(
343 pa_sink_input **i,
344 pa_core *core,
345 pa_sink_input_new_data *data);
346
347 void pa_sink_input_put(pa_sink_input *i);
348 void pa_sink_input_unlink(pa_sink_input* i);
349
350 pa_usec_t pa_sink_input_set_requested_latency(pa_sink_input *i, pa_usec_t usec);
351
352 /* Request that the specified number of bytes already written out to
353 the hw device is rewritten, if possible. Please note that this is
354 only a kind request. The sink driver may not be able to fulfill it
355 fully -- or at all. If the request for a rewrite was successful, the
356 sink driver will call ->rewind() and pass the number of bytes that
357 could be rewound in the HW device. This functionality is required for
358 implementing the "zero latency" write-through functionality. */
359 void pa_sink_input_request_rewind(pa_sink_input *i, size_t nbytes, bool rewrite, bool flush, bool dont_rewind_render);
360
361 void pa_sink_input_cork(pa_sink_input *i, bool b);
362
363 int pa_sink_input_set_rate(pa_sink_input *i, uint32_t rate);
364 int pa_sink_input_update_resampler(pa_sink_input *i);
365
366 /* This returns the sink's fields converted into out sample type */
367 size_t pa_sink_input_get_max_rewind(pa_sink_input *i);
368 size_t pa_sink_input_get_max_request(pa_sink_input *i);
369
370 /* Callable by everyone from main thread*/
371
372 /* External code may request disconnection with this function */
373 void pa_sink_input_kill(pa_sink_input*i);
374
375 pa_usec_t pa_sink_input_get_latency(pa_sink_input *i, pa_usec_t *sink_latency);
376
377 bool pa_sink_input_is_passthrough(pa_sink_input *i);
378 bool pa_sink_input_is_volume_readable(pa_sink_input *i);
379 void pa_sink_input_set_volume(pa_sink_input *i, const pa_cvolume *volume, bool save, bool absolute);
380 void pa_sink_input_add_volume_factor(pa_sink_input *i, const char *key, const pa_cvolume *volume_factor);
381 int pa_sink_input_remove_volume_factor(pa_sink_input *i, const char *key);
382 pa_cvolume *pa_sink_input_get_volume(pa_sink_input *i, pa_cvolume *volume, bool absolute);
383
384 void pa_sink_input_set_mute(pa_sink_input *i, bool mute, bool save);
385
386 void pa_sink_input_set_property(pa_sink_input *i, const char *key, const char *value);
387 void pa_sink_input_set_property_arbitrary(pa_sink_input *i, const char *key, const uint8_t *value, size_t nbytes);
388 void pa_sink_input_update_proplist(pa_sink_input *i, pa_update_mode_t mode, pa_proplist *p);
389
390 pa_resample_method_t pa_sink_input_get_resample_method(pa_sink_input *i);
391
392 void pa_sink_input_send_event(pa_sink_input *i, const char *name, pa_proplist *data);
393
394 int pa_sink_input_move_to(pa_sink_input *i, pa_sink *dest, bool save);
395 bool pa_sink_input_may_move(pa_sink_input *i); /* may this sink input move at all? */
396 bool pa_sink_input_may_move_to(pa_sink_input *i, pa_sink *dest); /* may this sink input move to this sink? */
397
398 /* The same as pa_sink_input_move_to() but in two separate steps,
399 * first the detaching from the old sink, then the attaching to the
400 * new sink */
401 int pa_sink_input_start_move(pa_sink_input *i);
402 int pa_sink_input_finish_move(pa_sink_input *i, pa_sink *dest, bool save);
403 void pa_sink_input_fail_move(pa_sink_input *i);
404
405 pa_usec_t pa_sink_input_get_requested_latency(pa_sink_input *i);
406
407 /* To be used exclusively by the sink driver IO thread */
408
409 void pa_sink_input_peek(pa_sink_input *i, size_t length, pa_memchunk *chunk, pa_cvolume *volume);
410 void pa_sink_input_drop(pa_sink_input *i, size_t length);
411 void pa_sink_input_process_rewind(pa_sink_input *i, size_t nbytes /* in the sink's sample spec */);
412 void pa_sink_input_update_max_rewind(pa_sink_input *i, size_t nbytes /* in the sink's sample spec */);
413 void pa_sink_input_update_max_request(pa_sink_input *i, size_t nbytes /* in the sink's sample spec */);
414
415 void pa_sink_input_set_state_within_thread(pa_sink_input *i, pa_sink_input_state_t state);
416
417 int pa_sink_input_process_msg(pa_msgobject *o, int code, void *userdata, int64_t offset, pa_memchunk *chunk);
418
419 pa_usec_t pa_sink_input_set_requested_latency_within_thread(pa_sink_input *i, pa_usec_t usec);
420
421 bool pa_sink_input_safe_to_remove(pa_sink_input *i);
422 bool pa_sink_input_process_underrun(pa_sink_input *i);
423
424 pa_memchunk* pa_sink_input_get_silence(pa_sink_input *i, pa_memchunk *ret);
425
426 /* Calls the attach() callback if it's set. The input must be in detached
427 * state. */
428 void pa_sink_input_attach(pa_sink_input *i);
429
430 /* Calls the detach() callback if it's set and the input is attached. The input
431 * is allowed to be already detached, in which case this does nothing.
432 *
433 * The reason why this can be called for already-detached inputs is that when
434 * a filter sink's input is detached, it has to detach also all inputs
435 * connected to the filter sink. In case the filter sink's input was detached
436 * because the filter sink is being removed, those other inputs will be moved
437 * to another sink or removed, and moving and removing involve detaching the
438 * inputs, but the inputs at that point are already detached.
439 *
440 * XXX: Moving or removing an input also involves sending messages to the
441 * input's sink. If the input's sink is a detached filter sink, shouldn't
442 * sending messages to it be prohibited? The messages are processed in the
443 * root sink's IO thread, and when the filter sink is detached, it would seem
444 * logical to prohibit any interaction with the IO thread that isn't any more
445 * associated with the filter sink. Currently sending messages to detached
446 * filter sinks mostly works, because the filter sinks don't update their
447 * asyncmsgq pointer when detaching, so messages still find their way to the
448 * old IO thread. */
449 void pa_sink_input_detach(pa_sink_input *i);
450
451 /* Called from the main thread, from sink.c only. The normal way to set the
452 * sink input volume is to call pa_sink_input_set_volume(), but the flat volume
453 * logic in sink.c needs also a function that doesn't do all the extra stuff
454 * that pa_sink_input_set_volume() does. This function simply sets i->volume
455 * and fires change notifications. */
456 void pa_sink_input_set_volume_direct(pa_sink_input *i, const pa_cvolume *volume);
457
458 /* Called from the main thread, from sink.c only. This shouldn't be a public
459 * function, but the flat volume logic in sink.c currently needs a way to
460 * directly set the sink input reference ratio. This function simply sets
461 * i->reference_ratio and logs a message if the value changes. */
462 void pa_sink_input_set_reference_ratio(pa_sink_input *i, const pa_cvolume *ratio);
463
464 void pa_sink_input_set_preferred_sink(pa_sink_input *i, pa_sink *s);
465
466 #define pa_sink_input_assert_io_context(s) \
467 pa_assert(pa_thread_mq_get() || !PA_SINK_INPUT_IS_LINKED((s)->state))
468
469 #endif
470