1/* 2 * Copyright 2002-2010 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Christopher ML Zumwalt May, zummy@users.sf.net 7 * Omri Barak 8 * Proofreaders: 9 * John Scipione, jscipione@gmail.com 10 * Corresponds to: 11 * src/kits/game/GameProducer.h rev 43514 12 * src/kits/game/GameProducer.cpp rev 43514 13 */ 14 15 16/*! 17 \file GameProducer.h 18 \brief Provides the GameProducer class. 19*/ 20 21 22/*! 23 \class GameProducer 24 \ingroup game 25 \ingroup libbe 26 \brief A MediaKit producer node which mixes sound from the GameKit 27 and sends them to the audio mixer. 28*/ 29 30 31/*! 32 \fn GameProducer::GameProducer(GameSoundBuffer * object, 33 const gs_audio_format * format); 34 \brief Initializes the GameProducer with the passed in GameSoundBuffer 35 and gs_audio_format. 36 37 \param object The GameSoundBuffer to 'sync' the GameProducer with. 38 \param format The gs_audio_format to set the GameProducer's format. 39*/ 40 41 42/*! 43 \fn GameProducer::~GameProducer() 44 \brief Destroys the GameProducer object and stops the BMediaEventLooper 45 thread. 46*/ 47 48 49/*! 50 \fn BMediaAddOn* GameProducer::AddOn(int32 *internal_id) const 51 \brief Unimplemented. 52*/ 53 54 55/*! 56 \fn status_t GameProducer::FormatSuggestionRequested(media_type type, 57 int32 quality, media_format* format) 58 \brief Checks if a certain media format works with the GameProducer. 59 60 \warning Only supports raw audio at this point. 61 62 \param type The media format being tested. 63 \param quality The quality of the media -- Not used in the method. 64 \param format The media format to send through. 65 66 \returns A status code. 67 \retval B_OK \a type is supported. 68 \retval B_BAD_VALUE No \a format was received. 69 \retval B_MEDIA_BAD_FORMAT The \a format is not supported. 70*/ 71 72 73/*! 74 \fn status_t GameProducer::FormatProposal(const media_source& output, 75 media_format* format) 76 \brief Attempts to change the media format. 77 78 \warning Only supports raw audio and wildcard audio types. 79 80 \param output The source that the media outputs to. 81 \param format The type of media being proposed. 82 83 \returns A status code. 84 \retval B_OK The \a format is supported. 85 \retval B_MEDIA_BAD_SOURCE The \a output doesn't match the current 86 output source. 87 \retval B_MEDIA_BAD_FORMAT The \a format is not supported. 88 89*/ 90 91 92/*! 93 \fn status_t GameProducer::FormatChangeRequested(const media_source& source, 94 const media_destination& destination, media_format* io_format, 95 int32* _deprecated_) 96 \brief We don't support any other formats, so we just reject any format changes. 97 98 \attention This method is deprecated. 99 100 \param source The output source. 101 \param destination The media's destination. 102 \param io_format The format of the media 103 \param _deprecated_ This method is deprecated. 104 105 \returns B_ERROR as this function is deprecated, it has been removed, and 106 now only returns \a B_ERROR. 107*/ 108 109 110/*! 111 \fn status_t GameProducer::GetNextOutput(int32* cookie, 112 media_output* out_output) 113 \brief Gets the next output cookie. 114 115 Cookie can only be zero, as GameProducer supports one output. 116 117 \param cookie The output cookie value. 118 \param out_output The output that the cookie represents. 119 120 \returns A status code. 121 \retval B_OK The cookie was successfully incremented. 122 \retval B_BAD_INDEX The cookie is not equal to zero. 123*/ 124 125 126/*! 127 \fn status_t GameProducer::DisposeOutputCookie(int32 cookie) 128 \brief Does nothing because the cookie has no use as of yet. 129 130 \param cookie The cookie index. 131 132 \return Always returns B_OK. 133*/ 134 135 136/*! 137 \fn status_t GameProducer::SetBufferGroup(const media_source& for_source, 138 BBufferGroup* newGroup) 139 \brief Changes the buffer group from the current one, to the specified one. 140 141 \param for_source The output source. Can't be equivalent to the current 142 output source. 143 \param newGroup The new BBufferGroup to assign the buffer group to. 144 145 \returns A status code. 146 \retval B_OK The change has succeeded. 147 \retval B_MEDIA_BAD_SOURCE \a for_source is equal to the current output source. 148 \retval B_BAD_VALUE The new BBufferGroup's buffer list returns an error. 149*/ 150 151 152/*! 153 \fn status_t GameProducer::GetLatency(bigtime_t* out_latency) 154 \brief Gets the total latency, including internal downstream plus scheduling. 155 156 \param out_latency Gets set to the current latency. 157 158 \returns B_OK. 159*/ 160 161 162/*! 163 \fn status_t GameProducer::PrepareToConnect(const media_source& what, 164 const media_destination& where, media_format* format, 165 media_source* out_source, char* out_name) 166 \brief Confirms that the media format and wild cards are valid. 167 168 \param what The media source to output to. 169 \param where The destination for the connection. 170 \param format The format to finish specializing. 171 \param out_source The output source that the method retrieves. 172 \param out_name The variable that holds the output name. 173 174 \returns A status code. 175 \retval B_OK The connection preparations have finished. 176 \retval B_MEDIA_BAD_SOURCE The \a output doesn't match the current output source. 177 \retval B_MEDIA_ALREADY_CONNECTED The GameProducer is already connected. 178 \retval B_MEDIA_BAD_FORMAT The \a format is not supported. 179 180*/ 181 182 183/*! 184 \fn void GameProducer::Connect(status_t error, const media_source& source, 185 const media_destination& destination, const media_format& format, char* io_name) 186 \brief Connects to the output device. 187 188 \param error The variable that holds an error, should one arise. 189 \param source The output source to connect to. 190 \param destination The media destination, that is connected to. 191 \param format The variable that holds the format type. 192 \param io_name The variable that holds the output name. 193*/ 194 195 196/*! 197 \fn void GameProducer::Disconnect(const media_source& what, const media_destination& where) 198 \brief Disconnects from the output device. 199 200 \param what The media destination. 201 \param where The media's output source. 202*/ 203 204 205/*! 206 \fn void GameProducer::LateNoticeReceived(const media_source& what, 207 bigtime_t how_much, bigtime_t performance_time) 208 \brief Attempts to catch up to the buffer. 209 210 \param what The media output source. 211 \param how_much The amount of 'lateness'. 212 \param performance_time Unused. 213*/ 214 215 216/*! 217 \fn void GameProducer::EnableOutput(const media_source& what, 218 bool enabled, int32* _deprecated_) 219 \brief Enable or disable an output. 220 221 \attention This method is deprecated. 222 223 \param what The media output source. 224 \param enabled Sets the output to enabled or disabled. 225 \param _deprecated_ This method is deprecated. 226*/ 227 228 229/*! 230 \fn status_t GameProducer::SetPlayRate(int32 numer, int32 denom) 231 \brief Play rates are not supported, returns \c B_ERROR. 232 233 \param numer The top part of the fraction. 234 \param denom The bottom part of the fraction. 235 236 \return Always returns \c B_ERROR since play rates aren't supported. 237*/ 238 239 240/*! 241 \fn status_t GameProducer::HandleMessage(int32 message, const void* data, 242 size_t size) 243 \brief Private messages are not supported, returns \c B_ERROR. 244 245 \param message The message to be sent. 246 \param data The data to be sent. 247 \param size The size of the message. 248 249 \returns Always returns \c B_ERROR since private messages aren't supported. 250*/ 251 252 253/*! 254 \fn void GameProducer::AdditionalBufferRequested( 255 const media_source& source, 256 media_buffer_id prev_buffer, bigtime_t prev_time, 257 const media_seek_tag* prev_tag) 258 \brief Offline modes are not supported for now, does nothing. 259 260 \param source The media output source. 261 \param prev_buffer The previous buffer. 262 \param prev_time The previous buffer time. 263 \param prev_tag The previous buffer delimiter. 264*/ 265 266 267/*! 268 \fn void GameProducer::LatencyChanged(const media_source& source, 269 const media_destination& destination, bigtime_t new_latency, 270 uint32 flags) 271 \brief Sets the event latency in the case that the latency changed. 272 273 \param source The media output source. 274 \param destination The connected output destination. 275 \param new_latency The new amount of latency. 276 \param flags Unused. 277*/ 278 279 280/*! 281 \fn void GameProducer::NodeRegistered() 282 \brief Handles when an output source node is registered. 283*/ 284 285 286/*! 287 \fn void GameProducer::SetRunMode(run_mode mode) 288 \brief Offline mode is not supported. 289 290 \param mode The mode of running. 291*/ 292 293 294/*! 295 \fn void GameProducer::HandleEvent(const media_timed_event* event, bigtime_t lateness, 296 bool realTimeEvent) 297 \brief Handles when an event is triggered. 298 299 \param event The type of event. 300 \param lateness Unused. 301 \param realTimeEvent Unused. 302*/ 303