xref: /haiku/docs/user/game/GameProducer.dox (revision dd3b190b55747576443300d2d3531dde5bde3741)

/*
 * 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
	\ingroup game
	\ingroup libbe
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\fn GameProducer::~GameProducer()
	\brief Destroys the GameProducer object and stops the BMediaEventLooper
	       thread.

	\since Haiku R1
*/


/*!
	\fn BMediaAddOn* GameProducer::AddOn(int32* internal_id) const
	\brief Unimplemented.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\fn status_t GameProducer::GetNextOutput(int32* cookie,
		media_output* _output)
	\brief Gets the next output cookie.

	Cookie can only be zero, as GameProducer supports one output.

	\param cookie The output cookie value.
	\param _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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\fn status_t GameProducer::SetBufferGroup(const media_source& forSource,
		BBufferGroup* newGroup)
	\brief Changes the buffer group from the current one, to the specified one.

	\param forSource 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 forSource is equal to the current output source.
	\retval B_BAD_VALUE The new BBufferGroup's buffer list returns an error.

	\since Haiku R1
*/


/*!
	\fn status_t GameProducer::GetLatency(bigtime_t* _latency)
	\brief Gets the total latency, including internal downstream plus scheduling.

	\param _latency Gets set to the current latency.

	\returns B_OK.

	\since Haiku R1
*/


/*!
	\fn status_t GameProducer::PrepareToConnect(const media_source& what,
		const media_destination& where, media_format* format,
		media_source* _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 _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.


	\since Haiku R1
*/


/*!
	\fn void GameProducer::Connect(status_t error, const media_source& source,
		const media_destination& destination, const media_format& format,
		char* ioName)
	\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 ioName 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.

	\since Haiku R1
*/


/*!
	\fn void GameProducer::LateNoticeReceived(const media_source& what,
		bigtime_t howMuch, bigtime_t performanceDuration)
	\brief Attempts to catch up to the buffer.

	\param what The media output source.
	\param howMuch The amount of 'lateness'.
	\param performanceDuration Unused.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\fn status_t GameProducer::SetPlayRate(int32 numerator, int32 denominator)
	\brief Play rates are not supported, returns \c B_ERROR.

	\param numerator The top part of the fraction.
	\param denominator The bottom part of the fraction.

	\return Always returns \c B_ERROR since play rates aren't supported.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/


/*!
	\fn void GameProducer::NodeRegistered()
	\brief Handles when an output source node is registered.

	\since Haiku R1
*/


/*!
	\fn void GameProducer::SetRunMode(run_mode mode)
	\brief Offline mode is not supported.

	\param mode The mode of running.

	\since Haiku R1
*/


/*!
	\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.

	\since Haiku R1
*/