docs/user/game/GameProducer.dox

   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 */