Update Game Kit docs.

Add \since to each method.
This commit is contained in:
John Scipione 2014-06-11 16:45:07 -04:00
parent 37fedaf849
commit dd3b190b55
3 changed files with 179 additions and 51 deletions

View File

@ -23,6 +23,8 @@
\enum direct_buffer_state
Direct buffer state constants
\since BeOS R3
*/
@ -30,6 +32,8 @@
\enum direct_driver_state
Direct driver state constants
\since BeOS R3
*/
@ -39,6 +43,8 @@
\ingroup libbe
Direct butter info struct
\since BeOS R3
*/
@ -55,6 +61,8 @@
- \c B_BUFFER_RESET
- \c B_BUFFER_RESIZED
- \c B_CLIPPING_MODIFIED
\since BeOS R3
*/
@ -65,6 +73,8 @@
There are two possible values:
- \c B_MODE_CHANGED The resolution or color depth has changed.
- \c B_DRIVER_CHANGED The window was moved onto another monitor.
\since BeOS R3
*/
@ -72,6 +82,8 @@
\var direct_buffer_info::bits
Pointer to the frame buffer in your team's memory space.
\since BeOS R3
*/
@ -80,12 +92,17 @@
Pointer to the frame buffer in the PCI memory space. This value is
typically needed to control DMA.
\since BeOS R3
*/
/*!
\var direct_buffer_info::bytes_per_row
Number of bytes used to represent a single row of pixels in the frame buffer.
\since BeOS R3
*/
@ -94,6 +111,8 @@
Number of bits actually used to store a single pixel, including reserved,
unused, or alpha channel bits. This value is usually a multiple of eight.
\since BeOS R3
*/
@ -101,6 +120,8 @@
\var direct_buffer_info::pixel_format
The format used to encode a pixel as defined by the \c color_space type.
\since BeOS R3
*/
@ -108,6 +129,8 @@
\var direct_buffer_info::layout
Reserved for future use.
\since BeOS R3
*/
@ -115,6 +138,8 @@
\var direct_buffer_info::orientation
Reserved for future use.
\since BeOS R3
*/
@ -122,6 +147,8 @@
\var direct_buffer_info::_reserved[9]
Reserved for future use.
\since BeOS R3
*/
@ -129,6 +156,8 @@
\var direct_buffer_info::_dd_type_
Reserved for future use.
\since BeOS R3
*/
@ -136,6 +165,8 @@
\var direct_buffer_info::_dd_token_
Reserved for future use.
\since BeOS R3
*/
@ -143,6 +174,8 @@
\var direct_buffer_info::clip_list_count
Number of rectangles in \c clip_list.
\since BeOS R3
*/
@ -151,6 +184,8 @@
Rectangle that defines the full content area of the window in screen
coordinates.
\since BeOS R3
*/
@ -159,6 +194,8 @@
Bounding rectangle of the visible part of the content area of the window
in screen coordinates.
\since BeOS R3
*/
@ -167,6 +204,8 @@
List of rectangles that together define the visible region of the content
area of the window in screen coordinates.
\since BeOS R3
*/
@ -175,11 +214,13 @@
\ingroup game
\ingroup libbe
\brief Provides direct access to the video card graphics frame buffer.
\since BeOS R3
*/
/*!
\fn BDirectWindow::BDirectWindow(BRect frame, const char *title,
\fn BDirectWindow::BDirectWindow(BRect frame, const char* title,
window_type type, uint32 flags, uint32 workspace)
\brief Creates and initializes a BDirectWindow object.
@ -188,11 +229,13 @@
\param type Window type (see BWindow).
\param flags Window flags (see BWindow).
\param workspace Workspace of the direct window (see BWindow).
\since BeOS R3
*/
/*!
\fn BDirectWindow::BDirectWindow(BRect frame, const char *title,
\fn BDirectWindow::BDirectWindow(BRect frame, const char* title,
window_look look, window_feel feel, uint32 flags, uint32 workspace)
\brief Creates and initializes a BDirectWindow object.
@ -202,6 +245,8 @@
\param feel Window feel (see BWindow).
\param flags Window flags (see BWindow).
\param workspace Workspace of the direct window (see BWindow).
\since BeOS R3
*/
@ -221,42 +266,50 @@
disconnect from direct access.
Once these steps are complete you may do your usual destructor work.
\since BeOS R3
*/
/*!
\fn BArchivable* BDirectWindow::Instantiate(BMessage *data)
\fn BArchivable* BDirectWindow::Instantiate(BMessage* data)
\brief Instantiate window from message \a data. Not implemented.
\since BeOS R3
*/
/*!
\fn status_t BDirectWindow::Archive(BMessage *data, bool deep) const
\fn status_t BDirectWindow::Archive(BMessage* data, bool deep) const
\brief Archive window into message \a data. Not implemented.
\since BeOS R3
*/
/*!
\fn void BDirectWindow::DirectConnected(direct_buffer_info *info)
\brief hook function called when your application learns about the state
of the graphics display and changes occur.
\fn void BDirectWindow::DirectConnected(direct_buffer_info* info)
\brief Hook method called when your application learns about the state
of the graphics display and changes occur.
This is the heart of BDirectWindow.
\param info The \c direct_buffer_info struct
\since BeOS R3
*/
/*!
\fn status_t BDirectWindow::GetClippingRegion(BRegion *region,
BPoint *origin) const
\fn status_t BDirectWindow::GetClippingRegion(BRegion* region,
BPoint* origin) const
\brief Sets \a region to the current clipping region of the direct window.
If \a origin is not \c NULL, the \a region is offset by \a origin.
\warning GetClippingRegion() should only be called from within the
DirectConnected() method. If called outside GetClippingRegion() will
return \c B_ERROR.
DirectConnected() method. If called outside GetClippingRegion()
will return \c B_ERROR.
\param region The clipping region to fill out.
\param origin An origin to offset the region by.
@ -266,6 +319,8 @@
\retval B_BAD_VALUE \a region was NULL.
\retval B_ERROR Window not locked or not in DirectConnected() method.
\retval B_NO_MEMORY Not enough memory to fill \a region
\since BeOS R3
*/
@ -284,9 +339,11 @@
\returns A status code.
\retval B_OK Everything went as expected.
\retval B_ERROR An error occurred while trying to switch between full screen
and windowed mode.
and windowed mode.
\see BDirectWindow::SupportsWindowMode()
\since BeOS R3
*/
@ -295,6 +352,8 @@
\brief Returns whether the window is in full-screen or windowed mode.
\returns \c true if in full-screen mode, \c false if in windowed mode.
\since BeOS R3
*/
@ -306,7 +365,9 @@
BDirectWindow object to call it.
\param id The id of the screen you want to check, \c B_MAIN_SCREEN_ID by
default.
default.
\returns \c true if the screen support windowed mode, \c false otherwise.
\since BeOS R3
*/

View File

@ -24,12 +24,14 @@
\ingroup game
\ingroup libbe
\brief Playback audio from a sound file on disk.
\since BeOS R5
*/
/*!
\fn BFileGameSound::BFileGameSound(const entry_ref *file, bool looping,
BGameSoundDevice *device)
\fn BFileGameSound::BFileGameSound(const entry_ref* file, bool looping,
BGameSoundDevice* device)
\brief Creates and initializes a BFileGameSound object from an
\c entry_ref allowing you to play the specified sound file.
@ -44,12 +46,14 @@
\param looping Whether or not to repeat the sound in a loop.
\param device The sound device to use to play the sound, use \c NULL for
default.
\since BeOS R5
*/
/*!
\fn BFileGameSound::BFileGameSound(const char *file, bool looping,
BGameSoundDevice *device)
\fn BFileGameSound::BFileGameSound(const char* file, bool looping,
BGameSoundDevice* device)
\brief Creates and initializes a BFileGameSound object from a file path
allowing you to play the specified sound file.
@ -63,19 +67,25 @@
\param file The path of the sound file on disk.
\param looping Whether or not to repeat the sound in a loop.
\param device The sound device to use to play the sound, use \c NULL for
default.
default.
\since BeOS R5
*/
/*!
\fn BFileGameSound::~BFileGameSound()
\brief Destroys the BFileGameSound object.
\since BeOS R5
*/
/*!
\fn BGameSound* BFileGameSound::Clone() const
\brief Not implemented, always returns \c NULL.
\since BeOS R5
*/
@ -84,6 +94,8 @@
\brief Plays the sound file.
\returns A status code, \c B_OK on success or an error code on error.
\since BeOS R5
*/
@ -92,6 +104,8 @@
\brief Stops playback of the sound file.
\returns A status code, \c B_OK on success or an error code on error.
\since BeOS R5
*/
@ -100,32 +114,38 @@
\brief Preload the sound file into memory so that playback won't be delayed.
\returns A status code, \c B_OK on success or an error code if we were
unable to communicate with the sound port.
unable to communicate with the sound port.
\since BeOS R5
*/
/*!
\fn void BFileGameSound::FillBuffer(void *inBuffer, size_t inByteCount)
\fn void BFileGameSound::FillBuffer(void* inBuffer, size_t inByteCount)
\brief Fill a buffer with sound data.
\param inBuffer The buffer to fill.
\param inByteCount The number of bytes to fill buffer with.
\since BeOS R5
*/
/*!
\fn status_t BFileGameSound::SetPaused(bool isPaused, bigtime_t rampTime)
\brief Pauses playback if \a isPaused is \c true or resumes play if
\a isPaused is \c false.
\a isPaused is \c false.
\param isPaused \c true to pause playback, \c false to resume playback.
\param rampTime Determines how long the change in playback state should
take to complete in microseconds. Set to 0 for an instantaneous
change.
take to complete in microseconds. Set to 0 for an instantaneous
change.
\returns A status code.
\retval B_OK The playback state was updated.
\retval EALREADY Already in the requested playback state.
\since BeOS R5
*/
@ -137,4 +157,6 @@
\retval B_NOT_PAUSED Sound is playing.
\retval B_PAUSE_IN_PROGRESS The sound is transitioning to or from a paused state.
\retval B_PAUSED Sound is paused.
\since BeOS R5
*/

View File

@ -28,31 +28,39 @@
\ingroup game
\ingroup libbe
\brief A MediaKit producer node which mixes sound from the GameKit
and sends them to the audio mixer.
and sends them to the audio mixer.
\since Haiku R1
*/
/*!
\fn GameProducer::GameProducer(GameSoundBuffer * object,
const gs_audio_format * format);
\fn GameProducer::GameProducer(GameSoundBuffer* object,
const gs_audio_format* format);
\brief Initializes the GameProducer with the passed in GameSoundBuffer
and gs_audio_format.
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.
thread.
\since Haiku R1
*/
/*!
\fn BMediaAddOn* GameProducer::AddOn(int32 *internal_id) const
\fn BMediaAddOn* GameProducer::AddOn(int32* internal_id) const
\brief Unimplemented.
\since Haiku R1
*/
@ -71,6 +79,8 @@
\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
*/
@ -87,9 +97,10 @@
\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.
output source.
\retval B_MEDIA_BAD_FORMAT The \a format is not supported.
\since Haiku R1
*/
@ -107,23 +118,27 @@
\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.
now only returns \a B_ERROR.
\since Haiku R1
*/
/*!
\fn status_t GameProducer::GetNextOutput(int32* cookie,
media_output* out_output)
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 out_output The output that the cookie represents.
\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
*/
@ -134,45 +149,51 @@
\param cookie The cookie index.
\return Always returns B_OK.
\since Haiku R1
*/
/*!
\fn status_t GameProducer::SetBufferGroup(const media_source& for_source,
\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 for_source The output source. Can't be equivalent to the current
\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 for_source is equal to the current output source.
\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* out_latency)
\fn status_t GameProducer::GetLatency(bigtime_t* _latency)
\brief Gets the total latency, including internal downstream plus scheduling.
\param out_latency Gets set to the current latency.
\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* out_source, char* out_name)
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 out_source The output source that the method retrieves.
\param _source The output source that the method retrieves.
\param out_name The variable that holds the output name.
\returns A status code.
@ -181,39 +202,47 @@
\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* io_name)
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 io_name The variable that holds the output name.
\param ioName The variable that holds the output name.
*/
/*!
\fn void GameProducer::Disconnect(const media_source& what, const media_destination& where)
\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 how_much, bigtime_t performance_time)
bigtime_t howMuch, bigtime_t performanceDuration)
\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.
\param howMuch The amount of 'lateness'.
\param performanceDuration Unused.
\since Haiku R1
*/
@ -227,17 +256,21 @@
\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 numer, int32 denom)
\fn status_t GameProducer::SetPlayRate(int32 numerator, int32 denominator)
\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.
\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
*/
@ -251,6 +284,8 @@
\param size The size of the message.
\returns Always returns \c B_ERROR since private messages aren't supported.
\since Haiku R1
*/
@ -265,6 +300,8 @@
\param prev_buffer The previous buffer.
\param prev_time The previous buffer time.
\param prev_tag The previous buffer delimiter.
\since Haiku R1
*/
@ -278,12 +315,16 @@
\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
*/
@ -292,15 +333,19 @@
\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)
\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
*/