1 #ifndef foopulsesinkinputhfoo
2 #define foopulsesinkinputhfoo
5 This file is part of PulseAudio.
7 Copyright 2004-2006 Lennart Poettering
8 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
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.
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.
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
28 typedef struct pa_sink_input pa_sink_input;
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>
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;
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;
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;
68 struct pa_sink_input {
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;
80 char *driver; /* may be NULL */
81 pa_proplist *proplist;
83 pa_module *module; /* may be NULL */
84 pa_client *client; /* may be NULL */
86 pa_sink *sink; /* NULL while we are being moved */
87 pa_sink *origin_sink; /* only set by filter sinks */
89 /* A sink input may be connected to multiple source outputs
90 * directly, so that they don't get mixed data of the entire
92 pa_idxset *direct_outputs;
94 pa_sample_spec sample_spec;
95 pa_channel_map channel_map;
96 pa_format_info *format;
98 pa_sink_input *sync_prev, *sync_next;
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 */
107 pa_cvolume volume_factor_sink; /* A second volume factor in format of the sink this stream is connected to */
109 pa_bool_t volume_writable:1;
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
117 pa_bool_t save_sink:1, save_volume:1, save_muted:1;
119 /* for volume ramps */
120 pa_cvolume_ramp_int ramp;
122 pa_resample_method_t requested_resample_method, actual_resample_method;
124 /* Returns the chunk of audio data and drops it from the
125 * queue. Returns -1 on failure. Called from IO thread context. If
126 * data needs to be generated from scratch then please in the
127 * specified length request_nbytes. This is an optimization
128 * only. If less data is available, it's fine to return a smaller
129 * block. If more data is already ready, it is better to return
131 int (*pop) (pa_sink_input *i, size_t request_nbytes, pa_memchunk *chunk); /* may NOT be NULL */
133 /* Rewind the queue by the specified number of bytes. Called just
134 * before peek() if it is called at all. Only called if the sink
135 * input driver ever plans to call
136 * pa_sink_input_request_rewind(). Called from IO context. */
137 void (*process_rewind) (pa_sink_input *i, size_t nbytes); /* may NOT be NULL */
139 /* Called whenever the maximum rewindable size of the sink
140 * changes. Called from IO context. */
141 void (*update_max_rewind) (pa_sink_input *i, size_t nbytes); /* may be NULL */
143 /* Called whenever the maximum request size of the sink
144 * changes. Called from IO context. */
145 void (*update_max_request) (pa_sink_input *i, size_t nbytes); /* may be NULL */
147 /* Called whenever the configured latency of the sink
148 * changes. Called from IO context. */
149 void (*update_sink_requested_latency) (pa_sink_input *i); /* may be NULL */
151 /* Called whenever the latency range of the sink changes. Called
152 * from IO context. */
153 void (*update_sink_latency_range) (pa_sink_input *i); /* may be NULL */
155 /* Called whenever the fixed latency of the sink changes, if there
156 * is one. Called from IO context. */
157 void (*update_sink_fixed_latency) (pa_sink_input *i); /* may be NULL */
159 /* If non-NULL this function is called when the input is first
160 * connected to a sink or when the rtpoll/asyncmsgq fields
161 * change. You usually don't need to implement this function
162 * unless you rewrite a sink that is piggy-backed onto
163 * another. Called from IO thread context */
164 void (*attach) (pa_sink_input *i); /* may be NULL */
166 /* If non-NULL this function is called when the output is
167 * disconnected from its sink. Called from IO thread context */
168 void (*detach) (pa_sink_input *i); /* may be NULL */
170 /* If non-NULL called whenever the sink this input is attached
171 * to suspends or resumes. Called from main context */
172 void (*suspend) (pa_sink_input *i, pa_bool_t b); /* may be NULL */
174 /* If non-NULL called whenever the sink this input is attached
175 * to suspends or resumes. Called from IO context */
176 void (*suspend_within_thread) (pa_sink_input *i, pa_bool_t b); /* may be NULL */
178 /* If non-NULL called whenever the sink input is moved to a new
179 * sink. Called from main context after the sink input has been
180 * detached from the old sink and before it has been attached to
181 * the new sink. If dest is NULL the move was executed in two
182 * phases and the second one failed; the stream will be destroyed
183 * after this call. */
184 void (*moving) (pa_sink_input *i, pa_sink *dest); /* may be NULL */
186 /* Supposed to unlink and destroy this stream. Called from main
188 void (*kill) (pa_sink_input *i); /* may NOT be NULL */
190 /* Return the current latency (i.e. length of buffered audio) of
191 this stream. Called from main context. This is added to what the
192 PA_SINK_INPUT_MESSAGE_GET_LATENCY message sent to the IO thread
194 pa_usec_t (*get_latency) (pa_sink_input *i); /* may be NULL */
196 /* If non-NULL this function is called from thread context if the
197 * state changes. The old state is found in thread_info.state. */
198 void (*state_change) (pa_sink_input *i, pa_sink_input_state_t state); /* may be NULL */
200 /* If non-NULL this function is called before this sink input is
201 * move to a sink and if it returns FALSE the move will not
203 pa_bool_t (*may_move_to) (pa_sink_input *i, pa_sink *s); /* may be NULL */
205 /* If non-NULL this function is used to dispatch asynchronous
206 * control events. Called from main context. */
207 void (*send_event)(pa_sink_input *i, const char *event, pa_proplist* data); /* may be NULL */
209 /* If non-NULL this function is called whenever the sink input
210 * volume changes. Called from main context */
211 void (*volume_changed)(pa_sink_input *i); /* may be NULL */
213 /* If non-NULL this function is called whenever the sink input
214 * mute status changes. Called from main context */
215 void (*mute_changed)(pa_sink_input *i); /* may be NULL */
218 pa_sink_input_state_t state;
221 pa_cvolume soft_volume;
224 pa_bool_t attached:1; /* True only between ->attach() and ->detach() calls */
226 /* rewrite_nbytes: 0: rewrite nothing, (size_t) -1: rewrite everything, otherwise how many bytes to rewrite */
227 pa_bool_t rewrite_flush:1, dont_rewind_render:1;
228 size_t rewrite_nbytes;
229 uint64_t underrun_for, playing_for;
231 pa_sample_spec sample_spec;
233 pa_resampler *resampler; /* may be NULL */
235 /* We maintain a history of resampled audio data here. */
236 pa_memblockq *render_memblockq;
238 pa_sink_input *sync_prev, *sync_next;
240 /* The requested latency for the sink */
241 pa_usec_t requested_sink_latency;
243 pa_hashmap *direct_outputs;
245 pa_cvolume_ramp_int ramp;
251 PA_DECLARE_PUBLIC_CLASS(pa_sink_input);
252 #define PA_SINK_INPUT(o) pa_sink_input_cast(o)
255 PA_SINK_INPUT_MESSAGE_SET_SOFT_VOLUME,
256 PA_SINK_INPUT_MESSAGE_SET_SOFT_MUTE,
257 PA_SINK_INPUT_MESSAGE_GET_LATENCY,
258 PA_SINK_INPUT_MESSAGE_SET_RATE,
259 PA_SINK_INPUT_MESSAGE_SET_STATE,
260 PA_SINK_INPUT_MESSAGE_SET_REQUESTED_LATENCY,
261 PA_SINK_INPUT_MESSAGE_GET_REQUESTED_LATENCY,
262 PA_SINK_INPUT_MESSAGE_SET_VOLUME_RAMP,
263 PA_SINK_INPUT_MESSAGE_MAX
266 typedef struct pa_sink_input_send_event_hook_data {
267 pa_sink_input *sink_input;
270 } pa_sink_input_send_event_hook_data;
272 typedef struct pa_sink_input_new_data {
273 pa_sink_input_flags_t flags;
275 pa_proplist *proplist;
282 pa_sink *origin_sink;
284 pa_resample_method_t resample_method;
286 pa_sink_input *sync_base;
288 pa_sample_spec sample_spec;
289 pa_channel_map channel_map;
290 pa_format_info *format;
291 pa_idxset *req_formats;
292 pa_idxset *nego_formats;
294 pa_cvolume volume, volume_factor, volume_factor_sink;
297 pa_bool_t sample_spec_is_set:1;
298 pa_bool_t channel_map_is_set:1;
300 pa_bool_t volume_is_set:1, volume_factor_is_set:1, volume_factor_sink_is_set:1;
301 pa_bool_t muted_is_set:1;
303 pa_bool_t volume_is_absolute:1;
305 pa_bool_t volume_writable:1;
307 pa_bool_t save_sink:1, save_volume:1, save_muted:1;
308 } pa_sink_input_new_data;
310 pa_sink_input_new_data* pa_sink_input_new_data_init(pa_sink_input_new_data *data);
311 void pa_sink_input_new_data_set_sample_spec(pa_sink_input_new_data *data, const pa_sample_spec *spec);
312 void pa_sink_input_new_data_set_channel_map(pa_sink_input_new_data *data, const pa_channel_map *map);
313 pa_bool_t pa_sink_input_new_data_is_passthrough(pa_sink_input_new_data *data);
314 void pa_sink_input_new_data_set_volume(pa_sink_input_new_data *data, const pa_cvolume *volume);
315 void pa_sink_input_new_data_apply_volume_factor(pa_sink_input_new_data *data, const pa_cvolume *volume_factor);
316 void pa_sink_input_new_data_apply_volume_factor_sink(pa_sink_input_new_data *data, const pa_cvolume *volume_factor);
317 void pa_sink_input_new_data_set_muted(pa_sink_input_new_data *data, pa_bool_t mute);
318 pa_bool_t pa_sink_input_new_data_set_sink(pa_sink_input_new_data *data, pa_sink *s, pa_bool_t save);
319 pa_bool_t pa_sink_input_new_data_set_formats(pa_sink_input_new_data *data, pa_idxset *formats);
320 void pa_sink_input_new_data_done(pa_sink_input_new_data *data);
322 /* To be called by the implementing module only */
324 int pa_sink_input_new(
327 pa_sink_input_new_data *data);
329 void pa_sink_input_put(pa_sink_input *i);
330 void pa_sink_input_unlink(pa_sink_input* i);
332 void pa_sink_input_set_name(pa_sink_input *i, const char *name);
334 pa_usec_t pa_sink_input_set_requested_latency(pa_sink_input *i, pa_usec_t usec);
336 /* Request that the specified number of bytes already written out to
337 the hw device is rewritten, if possible. Please note that this is
338 only a kind request. The sink driver may not be able to fulfill it
339 fully -- or at all. If the request for a rewrite was successful, the
340 sink driver will call ->rewind() and pass the number of bytes that
341 could be rewound in the HW device. This functionality is required for
342 implementing the "zero latency" write-through functionality. */
343 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);
345 void pa_sink_input_cork(pa_sink_input *i, pa_bool_t b);
347 int pa_sink_input_set_rate(pa_sink_input *i, uint32_t rate);
348 int pa_sink_input_update_rate(pa_sink_input *i);
350 /* This returns the sink's fields converted into out sample type */
351 size_t pa_sink_input_get_max_rewind(pa_sink_input *i);
352 size_t pa_sink_input_get_max_request(pa_sink_input *i);
354 /* Callable by everyone from main thread*/
356 /* External code may request disconnection with this function */
357 void pa_sink_input_kill(pa_sink_input*i);
359 pa_usec_t pa_sink_input_get_latency(pa_sink_input *i, pa_usec_t *sink_latency);
361 pa_bool_t pa_sink_input_is_passthrough(pa_sink_input *i);
362 pa_bool_t pa_sink_input_is_volume_readable(pa_sink_input *i);
363 void pa_sink_input_set_volume(pa_sink_input *i, const pa_cvolume *volume, pa_bool_t save, pa_bool_t absolute);
364 pa_cvolume *pa_sink_input_get_volume(pa_sink_input *i, pa_cvolume *volume, pa_bool_t absolute);
366 void pa_sink_input_set_mute(pa_sink_input *i, pa_bool_t mute, pa_bool_t save);
367 pa_bool_t pa_sink_input_get_mute(pa_sink_input *i);
369 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);
371 void pa_sink_input_update_proplist(pa_sink_input *i, pa_update_mode_t mode, pa_proplist *p);
373 pa_resample_method_t pa_sink_input_get_resample_method(pa_sink_input *i);
375 void pa_sink_input_send_event(pa_sink_input *i, const char *name, pa_proplist *data);
377 int pa_sink_input_move_to(pa_sink_input *i, pa_sink *dest, pa_bool_t save);
378 pa_bool_t pa_sink_input_may_move(pa_sink_input *i); /* may this sink input move at all? */
379 pa_bool_t pa_sink_input_may_move_to(pa_sink_input *i, pa_sink *dest); /* may this sink input move to this sink? */
381 /* The same as pa_sink_input_move_to() but in two separate steps,
382 * first the detaching from the old sink, then the attaching to the
384 int pa_sink_input_start_move(pa_sink_input *i);
385 int pa_sink_input_finish_move(pa_sink_input *i, pa_sink *dest, pa_bool_t save);
386 void pa_sink_input_fail_move(pa_sink_input *i);
388 pa_sink_input_state_t pa_sink_input_get_state(pa_sink_input *i);
390 pa_usec_t pa_sink_input_get_requested_latency(pa_sink_input *i);
392 /* To be used exclusively by the sink driver IO thread */
394 void pa_sink_input_peek(pa_sink_input *i, size_t length, pa_memchunk *chunk, pa_cvolume *volume);
395 void pa_sink_input_drop(pa_sink_input *i, size_t length);
396 void pa_sink_input_process_rewind(pa_sink_input *i, size_t nbytes /* in the sink's sample spec */);
397 void pa_sink_input_update_max_rewind(pa_sink_input *i, size_t nbytes /* in the sink's sample spec */);
398 void pa_sink_input_update_max_request(pa_sink_input *i, size_t nbytes /* in the sink's sample spec */);
400 void pa_sink_input_set_state_within_thread(pa_sink_input *i, pa_sink_input_state_t state);
402 int pa_sink_input_process_msg(pa_msgobject *o, int code, void *userdata, int64_t offset, pa_memchunk *chunk);
404 pa_usec_t pa_sink_input_set_requested_latency_within_thread(pa_sink_input *i, pa_usec_t usec);
406 pa_bool_t pa_sink_input_safe_to_remove(pa_sink_input *i);
408 pa_memchunk* pa_sink_input_get_silence(pa_sink_input *i, pa_memchunk *ret);
410 #define pa_sink_input_assert_io_context(s) \
411 pa_assert(pa_thread_mq_get() || !PA_SINK_INPUT_IS_LINKED((s)->state))