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