From 8786818cf2b7afd3ea9979f06d3ead55cfef041b Mon Sep 17 00:00:00 2001 From: John Scipione Date: Sun, 18 Dec 2011 19:42:33 -0500 Subject: [PATCH] Add documentation for the GameProducer class in the Game Kit. This documentation was provided by Omri Barak, a student participating in Google Code Initiative (GCI) 2011. Signed off by John Scipione Since this is the first class documented in the Game Kit I also added a reference to the Game Kit to the API docs front page. --- docs/user/Doxyfile | 4 +- docs/user/book.dox | 7 + docs/user/game/GameProducer.dox | 302 ++++++++++++++++++++++++++++++++ 3 files changed, 312 insertions(+), 1 deletion(-) create mode 100644 docs/user/game/GameProducer.dox diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile index a91be8985d..b9f030f261 100644 --- a/docs/user/Doxyfile +++ b/docs/user/Doxyfile @@ -601,6 +601,7 @@ WARN_LOGFILE = INPUT = . \ app \ drivers \ + game \ interface \ keyboard \ locale \ @@ -619,7 +620,8 @@ INPUT = . \ ../../headers/os/midi2 \ ../../headers/os/storage \ ../../headers/os/support \ - ../../headers/posix/syslog.h + ../../headers/posix/syslog.h \ + ../../src/kits/game/GameProducer.h # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is diff --git a/docs/user/book.dox b/docs/user/book.dox index fcc37156c9..d057d81859 100644 --- a/docs/user/book.dox +++ b/docs/user/book.dox @@ -32,6 +32,8 @@ - The \ref app is the starting point for developing applications and includes classes for messaging and for interacting with the rest of the system. + - The \ref game provides classes for producing game sounds and + working with full screen apps. - The \ref interface is used to create responsive and attractive graphical user interfaces building on the messaging facilities provided by the Application Kit. @@ -97,6 +99,11 @@ - BRoster + \defgroup game Game Kit + \brief The Game Kit provides classes for producing game sounds and + working with full screen apps. + + \defgroup interface Interface Kit \brief API for displaying a graphical user interface. diff --git a/docs/user/game/GameProducer.dox b/docs/user/game/GameProducer.dox new file mode 100644 index 0000000000..535c048ddc --- /dev/null +++ b/docs/user/game/GameProducer.dox @@ -0,0 +1,302 @@ +/* + * Copyright 2002-2010 Haiku Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Christopher ML Zumwalt May, zummy@users.sf.net + * Omri Barak + * Proofreaders: + * John Scipione, jscipione@gmail.com + * Corresponds to: + * src/kits/game/GameProducer.h rev 43514 + * src/kits/game/GameProducer.cpp rev 43514 + */ + + +/*! + \file GameProducer.h + \brief Provides the GameProducer class. +*/ + + +/*! + \class GameProducer + \ingroup game + \ingroup libbe + \brief A MediaKit producer node which mixes sound from the GameKit + and sends them to the audio mixer. +*/ + + +/*! + \fn GameProducer::GameProducer(GameSoundBuffer * object, + const gs_audio_format * format); + \brief Initializes the GameProducer with the passed in GameSoundBuffer + and gs_audio_format. + + \param object The GameSoundBuffer to 'sync' the GameProducer with. + \param format The gs_audio_format to set the GameProducer's format. +*/ + + +/*! + \fn GameProducer::~GameProducer() + \brief Destroys the GameProducer object and stops the BMediaEventLooper + thread. +*/ + + +/*! + \fn BMediaAddOn* GameProducer::AddOn(int32 *internal_id) const + \brief Unimplemented. +*/ + + +/*! + \fn status_t GameProducer::FormatSuggestionRequested(media_type type, + int32 quality, media_format* format) + \brief Checks if a certain media format works with the GameProducer. + + \warning Only supports raw audio at this point. + + \param type The media format being tested. + \param quality The quality of the media -- Not used in the method. + \param format The media format to send through. + + \returns A status code. + \retval B_OK \a type is supported. + \retval B_BAD_VALUE No \a format was received. + \retval B_MEDIA_BAD_FORMAT The \a format is not supported. +*/ + + +/*! + \fn status_t GameProducer::FormatProposal(const media_source& output, + media_format* format) + \brief Attempts to change the media format. + + \warning Only supports raw audio and wildcard audio types. + + \param output The source that the media outputs to. + \param format The type of media being proposed. + + \returns A status code. + \retval B_OK The \a format is supported. + \retval B_MEDIA_BAD_SOURCE The \a output doesn't match the current + output source. + \retval B_MEDIA_BAD_FORMAT The \a format is not supported. + +*/ + + +/*! + \fn status_t GameProducer::FormatChangeRequested(const media_source& source, + const media_destination& destination, media_format* io_format, + int32* _deprecated_) + \brief We don't support any other formats, so we just reject any format changes. + + \attention This method is deprecated. + + \param source The output source. + \param destination The media's destination. + \param io_format The format of the media + \param _deprecated_ This method is deprecated. + + \returns B_ERROR as this function is deprecated, it has been removed, and + now only returns \a B_ERROR. +*/ + + +/*! + \fn status_t GameProducer::GetNextOutput(int32* cookie, + media_output* out_output) + \brief Gets the next output cookie. + + Cookie can only be zero, as GameProducer supports one output. + + \param cookie The output cookie value. + \param out_output The output that the cookie represents. + + \returns A status code. + \retval B_OK The cookie was successfully incremented. + \retval B_BAD_INDEX The cookie is not equal to zero. +*/ + + +/*! + \fn status_t GameProducer::DisposeOutputCookie(int32 cookie) + \brief Does nothing because the cookie has no use as of yet. + + \param cookie The cookie index. + + \return Always returns B_OK. +*/ + + +/*! + \fn status_t GameProducer::SetBufferGroup(const media_source& for_source, + BBufferGroup* newGroup) + \brief Changes the buffer group from the current one, to the specified one. + + \param for_source The output source. Can't be equivalent to the current + output source. + \param newGroup The new BBufferGroup to assign the buffer group to. + + \returns A status code. + \retval B_OK The change has succeeded. + \retval B_MEDIA_BAD_SOURCE \a for_source is equal to the current output source. + \retval B_BAD_VALUE The new BBufferGroup's buffer list returns an error. +*/ + + +/*! + \fn status_t GameProducer::GetLatency(bigtime_t* out_latency) + \brief Gets the total latency, including internal downstream plus scheduling. + + \param out_latency Gets set to the current latency. + + \returns B_OK. +*/ + + +/*! + \fn status_t GameProducer::PrepareToConnect(const media_source& what, + const media_destination& where, media_format* format, + media_source* out_source, char* out_name) + \brief Confirms that the media format and wild cards are valid. + + \param what The media source to output to. + \param where The destination for the connection. + \param format The format to finish specializing. + \param out_source The output source that the method retrieves. + \param out_name The variable that holds the output name. + + \returns A status code. + \retval B_OK The connection preparations have finished. + \retval B_MEDIA_BAD_SOURCE The \a output doesn't match the current output source. + \retval B_MEDIA_ALREADY_CONNECTED The GameProducer is already connected. + \retval B_MEDIA_BAD_FORMAT The \a format is not supported. + +*/ + + +/*! + \fn void GameProducer::Connect(status_t error, const media_source& source, + const media_destination& destination, const media_format& format, char* io_name) + \brief Connects to the output device. + + \param error The variable that holds an error, should one arise. + \param source The output source to connect to. + \param destination The media destination, that is connected to. + \param format The variable that holds the format type. + \param io_name The variable that holds the output name. +*/ + + +/*! + \fn void GameProducer::Disconnect(const media_source& what, const media_destination& where) + \brief Disconnects from the output device. + + \param what The media destination. + \param where The media's output source. +*/ + + +/*! + \fn void GameProducer::LateNoticeReceived(const media_source& what, + bigtime_t how_much, bigtime_t performance_time) + \brief Attempts to catch up to the buffer. + + \param what The media output source. + \param how_much The amount of 'lateness'. + \param performance_time Unused. +*/ + + +/*! + \fn void GameProducer::EnableOutput(const media_source& what, + bool enabled, int32* _deprecated_) + \brief Enable or disable an output. + + \attention This method is deprecated. + + \param what The media output source. + \param enabled Sets the output to enabled or disabled. + \param _deprecated_ This method is deprecated. +*/ + + +/*! + \fn status_t GameProducer::SetPlayRate(int32 numer, int32 denom) + \brief Play rates are not supported, returns \c B_ERROR. + + \param numer The top part of the fraction. + \param denom The bottom part of the fraction. + + \return Always returns \c B_ERROR since play rates aren't supported. +*/ + + +/*! + \fn status_t GameProducer::HandleMessage(int32 message, const void* data, + size_t size) + \brief Private messages are not supported, returns \c B_ERROR. + + \param message The message to be sent. + \param data The data to be sent. + \param size The size of the message. + + \returns Always returns \c B_ERROR since private messages aren't supported. +*/ + + +/*! + \fn void GameProducer::AdditionalBufferRequested( + const media_source& source, + media_buffer_id prev_buffer, bigtime_t prev_time, + const media_seek_tag* prev_tag) + \brief Offline modes are not supported for now, does nothing. + + \param source The media output source. + \param prev_buffer The previous buffer. + \param prev_time The previous buffer time. + \param prev_tag The previous buffer delimiter. +*/ + + +/*! + \fn void GameProducer::LatencyChanged(const media_source& source, + const media_destination& destination, bigtime_t new_latency, + uint32 flags) + \brief Sets the event latency in the case that the latency changed. + + \param source The media output source. + \param destination The connected output destination. + \param new_latency The new amount of latency. + \param flags Unused. +*/ + + +/*! + \fn void GameProducer::NodeRegistered() + \brief Handles when an output source node is registered. +*/ + + +/*! + \fn void GameProducer::SetRunMode(run_mode mode) + \brief Offline mode is not supported. + + \param mode The mode of running. +*/ + + +/*! + \fn void GameProducer::HandleEvent(const media_timed_event* event, bigtime_t lateness, + bool realTimeEvent) + \brief Handles when an event is triggered. + + \param event The type of event. + \param lateness Unused. + \param realTimeEvent Unused. +*/