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
36typedef 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
44static 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
48typedef 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
63struct 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 rewindable size of the sink
160     * changes. Used by virtual sinks to communicate rewind limits
161     * of the virtual sink to the master sink. Must return size_t (-1)
162     * if there is no limit or if the virtual sink is not opened.
163     * Called from IO context. */
164    size_t (*get_max_rewind_limit) (pa_sink_input *i); /* may be NULL */
165
166    /* Called whenever the maximum request size of the sink
167     * changes. Called from IO context. */
168    void (*update_max_request) (pa_sink_input *i, size_t nbytes); /* may be NULL */
169
170    /* Called whenever the configured latency of the sink
171     * changes. Called from IO context. */
172    void (*update_sink_requested_latency) (pa_sink_input *i); /* may be NULL */
173
174    /* Called whenever the latency range of the sink changes. Called
175     * from IO context. */
176    void (*update_sink_latency_range) (pa_sink_input *i); /* may be NULL */
177
178    /* Called whenever the fixed latency of the sink changes, if there
179     * is one. Called from IO context. */
180    void (*update_sink_fixed_latency) (pa_sink_input *i); /* may be NULL */
181
182    /* If non-NULL this function is called when the input is first
183     * connected to a sink or when the rtpoll/asyncmsgq fields
184     * change. You usually don't need to implement this function
185     * unless you rewrite a sink that is piggy-backed onto
186     * another. Called from IO thread context */
187    void (*attach) (pa_sink_input *i);           /* may be NULL */
188
189    /* If non-NULL this function is called when the output is
190     * disconnected from its sink. Called from IO thread context */
191    void (*detach) (pa_sink_input *i);           /* may be NULL */
192
193    /* If non-NULL called whenever the sink this input is attached
194     * to suspends or resumes or if the suspend cause changes.
195     * Called from main context */
196    void (*suspend) (pa_sink_input *i, pa_sink_state_t old_state, pa_suspend_cause_t old_suspend_cause);   /* may be NULL */
197
198    /* If non-NULL called whenever the sink this input is attached
199     * to suspends or resumes. Called from IO context */
200    void (*suspend_within_thread) (pa_sink_input *i, bool b);   /* may be NULL */
201
202    /* If non-NULL called whenever the sink input is moved to a new
203     * sink. Called from main context after the sink input has been
204     * detached from the old sink and before it has been attached to
205     * the new sink. If dest is NULL the move was executed in two
206     * phases and the second one failed; the stream will be destroyed
207     * after this call. */
208    void (*moving) (pa_sink_input *i, pa_sink *dest);   /* may be NULL */
209
210    /* Supposed to unlink and destroy this stream. Called from main
211     * context. */
212    void (*kill) (pa_sink_input *i);             /* may NOT be NULL */
213
214    /* Return the current latency (i.e. length of buffered audio) of
215    this stream. Called from main context. This is added to what the
216    PA_SINK_INPUT_MESSAGE_GET_LATENCY message sent to the IO thread
217    returns */
218    pa_usec_t (*get_latency) (pa_sink_input *i); /* may be NULL */
219
220    /* If non-NULL this function is called from thread context if the
221     * state changes. The old state is found in thread_info.state.  */
222    void (*state_change) (pa_sink_input *i, pa_sink_input_state_t state); /* may be NULL */
223
224    /* If non-NULL this function is called before this sink input is
225     * move to a sink and if it returns false the move will not
226     * be allowed */
227    bool (*may_move_to) (pa_sink_input *i, pa_sink *s); /* may be NULL */
228
229    /* If non-NULL this function is used to dispatch asynchronous
230     * control events. Called from main context. */
231    void (*send_event)(pa_sink_input *i, const char *event, pa_proplist* data); /* may be NULL */
232
233    /* If non-NULL this function is called whenever the sink input
234     * volume changes. Called from main context */
235    void (*volume_changed)(pa_sink_input *i); /* may be NULL */
236
237    /* If non-NULL this function is called whenever the sink input
238     * mute status changes. Called from main context */
239    void (*mute_changed)(pa_sink_input *i); /* may be NULL */
240
241    bool (*process_underrun_ohos) (pa_sink_input *i);
242
243    /* Used to store the rewind amount of the origin sink during a move */
244    size_t origin_rewind_bytes;    /* In sink input sample spec */
245
246    struct {
247        pa_sink_input_state_t state;
248
249        pa_cvolume soft_volume;
250        bool muted:1;
251
252        bool attached:1; /* True only between ->attach() and ->detach() calls */
253
254        /* rewrite_nbytes: 0: rewrite nothing, (size_t) -1: rewrite everything, otherwise how many bytes to rewrite */
255        bool rewrite_flush:1, dont_rewind_render:1;
256        size_t rewrite_nbytes;
257        uint64_t underrun_for, playing_for;
258        uint64_t underrun_for_sink; /* Like underrun_for, but in sink sample spec */
259
260        pa_sample_spec sample_spec;
261
262        pa_resampler *resampler;                     /* may be NULL */
263
264        /* We maintain a history of resampled audio data here. */
265        pa_memblockq *render_memblockq;
266
267        /* This queue keeps the history before resampling and is used
268         * when rewinding the resampler. */
269        pa_memblockq *history_memblockq;
270
271        pa_sink_input *sync_prev, *sync_next;
272
273        /* The requested latency for the sink */
274        pa_usec_t requested_sink_latency;
275
276        /* Variables used during move */
277        pa_usec_t move_start_time;
278        pa_usec_t origin_sink_latency;
279        size_t resampler_delay_frames;
280        bool dont_rewrite;
281
282        pa_hashmap *direct_outputs;
283    } thread_info;
284
285    void *userdata;
286
287    pa_atomic_t isFirstReaded;
288};
289
290PA_DECLARE_PUBLIC_CLASS(pa_sink_input);
291#define PA_SINK_INPUT(o) pa_sink_input_cast(o)
292
293enum {
294    PA_SINK_INPUT_MESSAGE_SET_SOFT_VOLUME,
295    PA_SINK_INPUT_MESSAGE_SET_SOFT_MUTE,
296    PA_SINK_INPUT_MESSAGE_GET_LATENCY,
297    PA_SINK_INPUT_MESSAGE_SET_RATE,
298    PA_SINK_INPUT_MESSAGE_SET_STATE,
299    PA_SINK_INPUT_MESSAGE_SET_REQUESTED_LATENCY,
300    PA_SINK_INPUT_MESSAGE_GET_REQUESTED_LATENCY,
301    PA_SINK_INPUT_MESSAGE_MAX
302};
303
304typedef struct pa_sink_input_send_event_hook_data {
305    pa_sink_input *sink_input;
306    const char *event;
307    pa_proplist *data;
308} pa_sink_input_send_event_hook_data;
309
310typedef struct pa_sink_input_new_data {
311    pa_sink_input_flags_t flags;
312
313    pa_proplist *proplist;
314
315    const char *driver;
316    pa_module *module;
317    pa_client *client;
318
319    pa_sink *sink;
320    bool sink_requested_by_application;
321    pa_sink *origin_sink;
322
323    pa_resample_method_t resample_method;
324
325    pa_sink_input *sync_base;
326
327    pa_sample_spec sample_spec;
328    pa_channel_map channel_map;
329    pa_format_info *format;
330    pa_idxset *req_formats;
331    pa_idxset *nego_formats;
332
333    pa_cvolume volume;
334    bool muted:1;
335    pa_hashmap *volume_factor_items, *volume_factor_sink_items;
336
337    bool sample_spec_is_set:1;
338    bool channel_map_is_set:1;
339
340    bool volume_is_set:1;
341    bool muted_is_set:1;
342
343    bool volume_is_absolute:1;
344
345    bool volume_writable:1;
346
347    bool save_volume:1, save_muted:1;
348
349    char *preferred_sink;
350} pa_sink_input_new_data;
351
352pa_sink_input_new_data* pa_sink_input_new_data_init(pa_sink_input_new_data *data);
353void pa_sink_input_new_data_set_sample_spec(pa_sink_input_new_data *data, const pa_sample_spec *spec);
354void pa_sink_input_new_data_set_channel_map(pa_sink_input_new_data *data, const pa_channel_map *map);
355bool pa_sink_input_new_data_is_passthrough(pa_sink_input_new_data *data);
356void pa_sink_input_new_data_set_volume(pa_sink_input_new_data *data, const pa_cvolume *volume);
357void pa_sink_input_new_data_add_volume_factor(pa_sink_input_new_data *data, const char *key, const pa_cvolume *volume_factor);
358void pa_sink_input_new_data_add_volume_factor_sink(pa_sink_input_new_data *data, const char *key, const pa_cvolume *volume_factor);
359void pa_sink_input_new_data_set_muted(pa_sink_input_new_data *data, bool mute);
360bool pa_sink_input_new_data_set_sink(pa_sink_input_new_data *data, pa_sink *s, bool save, bool requested_by_application);
361bool pa_sink_input_new_data_set_formats(pa_sink_input_new_data *data, pa_idxset *formats);
362void pa_sink_input_new_data_done(pa_sink_input_new_data *data);
363
364/* To be called by the implementing module only */
365
366int pa_sink_input_new(
367        pa_sink_input **i,
368        pa_core *core,
369        pa_sink_input_new_data *data);
370
371void pa_sink_input_put(pa_sink_input *i);
372void pa_sink_input_unlink(pa_sink_input* i);
373
374pa_usec_t pa_sink_input_set_requested_latency(pa_sink_input *i, pa_usec_t usec);
375
376/* Request that the specified number of bytes already written out to
377the hw device is rewritten, if possible.  Please note that this is
378only a kind request. The sink driver may not be able to fulfill it
379fully -- or at all. If the request for a rewrite was successful, the
380sink driver will call ->rewind() and pass the number of bytes that
381could be rewound in the HW device. This functionality is required for
382implementing the "zero latency" write-through functionality. */
383void pa_sink_input_request_rewind(pa_sink_input *i, size_t nbytes, bool rewrite, bool flush, bool dont_rewind_render);
384
385void pa_sink_input_cork(pa_sink_input *i, bool b);
386
387int pa_sink_input_set_rate(pa_sink_input *i, uint32_t rate);
388int pa_sink_input_update_resampler(pa_sink_input *i, bool flush_history);
389
390/* This returns the sink's fields converted into out sample type */
391size_t pa_sink_input_get_max_rewind(pa_sink_input *i);
392size_t pa_sink_input_get_max_request(pa_sink_input *i);
393
394/* Callable by everyone from main thread*/
395
396/* External code may request disconnection with this function */
397void pa_sink_input_kill(pa_sink_input*i);
398
399pa_usec_t pa_sink_input_get_latency(pa_sink_input *i, pa_usec_t *sink_latency);
400
401bool pa_sink_input_is_passthrough(pa_sink_input *i);
402bool pa_sink_input_is_volume_readable(pa_sink_input *i);
403void pa_sink_input_set_volume(pa_sink_input *i, const pa_cvolume *volume, bool save, bool absolute);
404void pa_sink_input_add_volume_factor(pa_sink_input *i, const char *key, const pa_cvolume *volume_factor);
405int pa_sink_input_remove_volume_factor(pa_sink_input *i, const char *key);
406pa_cvolume *pa_sink_input_get_volume(pa_sink_input *i, pa_cvolume *volume, bool absolute);
407
408void pa_sink_input_set_mute(pa_sink_input *i, bool mute, bool save);
409
410void pa_sink_input_set_property(pa_sink_input *i, const char *key, const char *value);
411void pa_sink_input_set_property_arbitrary(pa_sink_input *i, const char *key, const uint8_t *value, size_t nbytes);
412void pa_sink_input_update_proplist(pa_sink_input *i, pa_update_mode_t mode, pa_proplist *p);
413
414pa_resample_method_t pa_sink_input_get_resample_method(pa_sink_input *i);
415
416void pa_sink_input_send_event(pa_sink_input *i, const char *name, pa_proplist *data);
417
418int pa_sink_input_move_to(pa_sink_input *i, pa_sink *dest, bool save);
419bool pa_sink_input_may_move(pa_sink_input *i); /* may this sink input move at all? */
420bool pa_sink_input_may_move_to(pa_sink_input *i, pa_sink *dest); /* may this sink input move to this sink? */
421
422/* The same as pa_sink_input_move_to() but in two separate steps,
423 * first the detaching from the old sink, then the attaching to the
424 * new sink */
425int pa_sink_input_start_move(pa_sink_input *i);
426int pa_sink_input_finish_move(pa_sink_input *i, pa_sink *dest, bool save);
427void pa_sink_input_fail_move(pa_sink_input *i);
428
429pa_usec_t pa_sink_input_get_requested_latency(pa_sink_input *i);
430
431/* To be used exclusively by the sink driver IO thread */
432
433void pa_sink_input_peek(pa_sink_input *i, size_t length, pa_memchunk *chunk, pa_cvolume *volume);
434void pa_sink_input_drop(pa_sink_input *i, size_t length);
435void pa_sink_input_process_rewind(pa_sink_input *i, size_t nbytes /* in the sink's sample spec */);
436void pa_sink_input_update_max_rewind(pa_sink_input *i, size_t nbytes  /* in the sink's sample spec */);
437void pa_sink_input_update_max_request(pa_sink_input *i, size_t nbytes  /* in the sink's sample spec */);
438
439void pa_sink_input_set_state_within_thread(pa_sink_input *i, pa_sink_input_state_t state);
440
441int pa_sink_input_process_msg(pa_msgobject *o, int code, void *userdata, int64_t offset, pa_memchunk *chunk);
442
443pa_usec_t pa_sink_input_set_requested_latency_within_thread(pa_sink_input *i, pa_usec_t usec);
444
445bool pa_sink_input_safe_to_remove(pa_sink_input *i);
446bool pa_sink_input_process_underrun(pa_sink_input *i);
447
448pa_memchunk* pa_sink_input_get_silence(pa_sink_input *i, pa_memchunk *ret);
449
450/* Calls the attach() callback if it's set. The input must be in detached
451 * state. */
452void pa_sink_input_attach(pa_sink_input *i);
453
454/* Calls the detach() callback if it's set and the input is attached. The input
455 * is allowed to be already detached, in which case this does nothing.
456 *
457 * The reason why this can be called for already-detached inputs is that when
458 * a filter sink's input is detached, it has to detach also all inputs
459 * connected to the filter sink. In case the filter sink's input was detached
460 * because the filter sink is being removed, those other inputs will be moved
461 * to another sink or removed, and moving and removing involve detaching the
462 * inputs, but the inputs at that point are already detached.
463 *
464 * XXX: Moving or removing an input also involves sending messages to the
465 * input's sink. If the input's sink is a detached filter sink, shouldn't
466 * sending messages to it be prohibited? The messages are processed in the
467 * root sink's IO thread, and when the filter sink is detached, it would seem
468 * logical to prohibit any interaction with the IO thread that isn't any more
469 * associated with the filter sink. Currently sending messages to detached
470 * filter sinks mostly works, because the filter sinks don't update their
471 * asyncmsgq pointer when detaching, so messages still find their way to the
472 * old IO thread. */
473void pa_sink_input_detach(pa_sink_input *i);
474
475/* Called from the main thread, from sink.c only. The normal way to set the
476 * sink input volume is to call pa_sink_input_set_volume(), but the flat volume
477 * logic in sink.c needs also a function that doesn't do all the extra stuff
478 * that pa_sink_input_set_volume() does. This function simply sets i->volume
479 * and fires change notifications. */
480void pa_sink_input_set_volume_direct(pa_sink_input *i, const pa_cvolume *volume);
481
482/* Called from the main thread, from sink.c only. This shouldn't be a public
483 * function, but the flat volume logic in sink.c currently needs a way to
484 * directly set the sink input reference ratio. This function simply sets
485 * i->reference_ratio and logs a message if the value changes. */
486void pa_sink_input_set_reference_ratio(pa_sink_input *i, const pa_cvolume *ratio);
487
488void pa_sink_input_set_preferred_sink(pa_sink_input *i, pa_sink *s);
489
490void pa_sink_input_handle_ohos_underrun(pa_sink_input *i);
491
492#define pa_sink_input_assert_io_context(s) \
493    pa_assert(pa_thread_mq_get() || !PA_SINK_INPUT_IS_LINKED((s)->state))
494
495#endif
496