src/output_all.h

   1 /*
   2  * Copyright (C) 2003-2010 The Music Player Daemon Project
   3  * http://www.musicpd.org
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18  */
  19
  20 /*
  21  * Functions for dealing with all configured (enabled) audion outputs
  22  * at once.
  23  *
  24  */
  25
  26 #ifndef OUTPUT_ALL_H
  27 #define OUTPUT_ALL_H
  28
  29 #include <stdbool.h>
  30 #include <stddef.h>
  31
  32 struct audio_format;
  33 struct music_buffer;
  34 struct music_chunk;
  35
  36 /**
  37  * Global initialization: load audio outputs from the configuration
  38  * file and initialize them.
  39  */
  40 void
  41 audio_output_all_init(void);
  42
  43 /**
  44  * Global finalization: free memory occupied by audio outputs.  All
  45  */
  46 void
  47 audio_output_all_finish(void);
  48
  49 /**
  50  * Returns the total number of audio output devices, including those
  51  * who are disabled right now.
  52  */
  53 unsigned int audio_output_count(void);
  54
  55 /**
  56  * Returns the "i"th audio output device.
  57  */
  58 struct audio_output *
  59 audio_output_get(unsigned i);
  60
  61 /**
  62  * Returns the audio output device with the specified name.  Returns
  63  * NULL if the name does not exist.
  64  */
  65 struct audio_output *
  66 audio_output_find(const char *name);
  67
  68 /**
  69  * Checks the "enabled" flag of all audio outputs, and if one has
  70  * changed, commit the change.
  71  */
  72 void
  73 audio_output_all_enable_disable(void);
  74
  75 /**
  76  * Opens all audio outputs which are not disabled.
  77  *
  78  * @param audio_format the preferred audio format, or NULL to reuse
  79  * the previous format
  80  * @param buffer the #music_buffer where consumed #music_chunk objects
  81  * should be returned
  82  * @return true on success, false on failure
  83  */
  84 bool
  85 audio_output_all_open(const struct audio_format *audio_format,
  86                       struct music_buffer *buffer);
  87
  88 /**
  89  * Closes all audio outputs.
  90  */
  91 void
  92 audio_output_all_close(void);
  93
  94 /**
  95  * Closes all audio outputs.  Outputs with the "always_on" flag are
  96  * put into pause mode.
  97  */
  98 void
  99 audio_output_all_release(void);
 100
 101 /**
 102  * Enqueue a #music_chunk object for playing, i.e. pushes it to a
 103  * #music_pipe.
 104  *
 105  * @param chunk the #music_chunk object to be played
 106  * @return true on success, false if no audio output was able to play
 107  * (all closed then)
 108  */
 109 bool
 110 audio_output_all_play(struct music_chunk *chunk);
 111
 112 /**
 113  * Checks if the output devices have drained their music pipe, and
 114  * returns the consumed music chunks to the #music_buffer.
 115  *
 116  * @return the number of chunks to play left in the #music_pipe
 117  */
 118 unsigned
 119 audio_output_all_check(void);
 120
 121 /**
 122  * Checks if the size of the #music_pipe is below the #threshold.  If
 123  * not, it attempts to synchronize with all output threads, and waits
 124  * until another #music_chunk is finished.
 125  *
 126  * @param threshold the maximum number of chunks in the pipe
 127  * @return true if there are less than #threshold chunks in the pipe
 128  */
 129 bool
 130 audio_output_all_wait(unsigned threshold);
 131
 132 /**
 133  * Puts all audio outputs into pause mode.  Most implementations will
 134  * simply close it then.
 135  */
 136 void
 137 audio_output_all_pause(void);
 138
 139 /**
 140  * Drain all audio outputs.
 141  */
 142 void
 143 audio_output_all_drain(void);
 144
 145 /**
 146  * Try to cancel data which may still be in the device's buffers.
 147  */
 148 void
 149 audio_output_all_cancel(void);
 150
 151 /**
 152  * Indicate that a new song will begin now.
 153  */
 154 void
 155 audio_output_all_song_border(void);
 156
 157 /**
 158  * Returns the "elapsed_time" stamp of the most recently finished
 159  * chunk.  A negative value is returned when no chunk has been
 160  * finished yet.
 161  */
 162 float
 163 audio_output_all_get_elapsed_time(void);
 164
 165 #endif