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