From 35ef5bd7e9414cf61ba88fabb96b9dc4884d4c63 Mon Sep 17 00:00:00 2001 From: dborth Date: Tue, 24 Nov 2009 03:57:27 +0000 Subject: [PATCH] update comments --- source/ngc/oggplayer.c | 57 ++++++------ source/ngc/oggplayer.h | 199 ++++++++++++++--------------------------- 2 files changed, 95 insertions(+), 161 deletions(-) diff --git a/source/ngc/oggplayer.c b/source/ngc/oggplayer.c index 689160d..1f7aa8d 100644 --- a/source/ngc/oggplayer.c +++ b/source/ngc/oggplayer.c @@ -1,39 +1,42 @@ /* Copyright (c) 2008 Francisco Muņoz 'Hermes' All rights reserved. - + Proper (standard) vorbis usage by Tantric, 2009 Threading modifications/corrections by Tantric, 2009 - Redistribution and use in source and binary forms, with or without modification, are - permitted provided that the following conditions are met: + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: - - Redistributions of source code must retain the above copyright notice, this list of - conditions and the following disclaimer. - - Redistributions in binary form must reproduce the above copyright notice, this list - of conditions and the following disclaimer in the documentation and/or other - materials provided with the distribution. - - The names of the contributors may not be used to endorse or promote products derived - from this software without specific prior written permission. + - Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + - Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + - The names of the contributors may not be used to endorse or promote products + derived from this software without specific prior written permission. - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY - EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL - THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, - PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE + FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -#ifndef NO_SOUND - -#include "oggplayer.h" +#include +#include +#include #include #include #include +#include "oggplayer.h" + /* functions to read the Ogg file from memory */ static struct @@ -440,11 +443,11 @@ void StopOgg() } } -int PlayOgg(char * buf, int buflen, int time_pos, int mode) +int PlayOgg(const void *buffer, s32 len, int time_pos, int mode) { StopOgg(); - private_ogg.fd = mem_open(buf, buflen); + private_ogg.fd = mem_open((char *)buffer, len); if (private_ogg.fd < 0) { @@ -522,10 +525,8 @@ s32 GetTimeOgg() { int ret; if (ogg_thread_running == 0 || private_ogg.fd < 0) - return 0; + return -1; ret = ((s32) ov_time_tell(&private_ogg.vf)); - if (ret < 0) - ret = 0; return ret; } @@ -535,5 +536,3 @@ void SetTimeOgg(s32 time_pos) if (time_pos >= 0) private_ogg.seek_time = time_pos; } - -#endif diff --git a/source/ngc/oggplayer.h b/source/ngc/oggplayer.h index 58b29af..c505040 100644 --- a/source/ngc/oggplayer.h +++ b/source/ngc/oggplayer.h @@ -5,37 +5,32 @@ Proper (standard) vorbis usage by Tantric, 2009 Threading modifications/corrections by Tantric, 2009 - Redistribution and use in source and binary forms, with or without modification, are - permitted provided that the following conditions are met: + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: - - Redistributions of source code must retain the above copyright notice, this list of - conditions and the following disclaimer. - - Redistributions in binary form must reproduce the above copyright notice, this list - of conditions and the following disclaimer in the documentation and/or other - materials provided with the distribution. - - The names of the contributors may not be used to endorse or promote products derived - from this software without specific prior written permission. + - Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + - Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + - The names of the contributors may not be used to endorse or promote products + derived from this software without specific prior written permission. - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY - EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL - THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, - PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE + FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -#ifndef NO_SOUND - #ifndef __OGGPLAYER_H__ #define __OGGPLAYER_H__ -#include -#include -#include - #ifdef __cplusplus extern "C" { @@ -49,129 +44,69 @@ extern "C" #define OGG_STATUS_PAUSED 2 #define OGG_STATUS_EOF 255 -/*------------------------------------------------------------------------------------------------------------------------------------------------------*/ -/* Player OGG functions */ -/*------------------------------------------------------------------------------------------------------------------------------------------------------*/ - -/* int PlayOgg(int fd, int time_pos, int mode); - - Play an Ogg file. This file can be loaded from memory (mem_open(void *ogg, int size_ogg)) or from device with open("device:file.ogg",O_RDONLY,0); - - NOTE: The file is closed by the player when you call PlayOgg(), StopOgg() or if it fail. - - -- Params --- - - fd: file descriptor from open() or mem_open() - - time_pos: initial time position in the file (in milliseconds). For example, use 30000 to advance 30 seconds - - mode: Use OGG_ONE_TIME or OGG_INFINITE_TIME. When you use OGG_ONE_TIME the sound stops and StatusOgg() return OGG_STATUS_EOF - - return: 0- Ok, -1 Error - - */ - -int PlayOgg(char * buf, int buflen, int time_pos, int mode); - -/*------------------------------------------------------------------------------------------------------------------------------------------------------*/ - -/* void StopOgg(); - - Stop an Ogg file. - - NOTE: The file is closed and the player thread is released - - -- Params --- - - - */ +/**************************************************************************** + * PlayOgg + * + * Creates a thread that starts playing from the specific Ogg buffer + * buffer - pointer to the start of the Ogg data + * len - length of Ogg file + * time_pos - initial time position at which to start playback + * mode - playback mode (OGG_ONE_TIME or OGG_INFINITE_TIME) + * returns: -1 on error, 0 on success + ***************************************************************************/ +int PlayOgg(const void *buffer, s32 len, int time_pos, int mode); +/**************************************************************************** + * StopOgg + * + * Stops playback. The player thread is shut down. + ***************************************************************************/ void StopOgg(); -/*------------------------------------------------------------------------------------------------------------------------------------------------------*/ - -/* void PauseOgg(int pause); - - Pause an Ogg file. - - -- Params --- - - pause: 0 -> continue, 1-> pause - - */ - +/**************************************************************************** + * PauseOgg + * + * Pauses playback. 0 -> continue, 1-> pause + ***************************************************************************/ void PauseOgg(int pause); -/*------------------------------------------------------------------------------------------------------------------------------------------------------*/ - -/* int StatusOgg(); - - Return the Ogg status - - -- Params --- - - - return: OGG_STATUS_RUNNING - OGG_STATUS_ERR -> not initialized? - OGG_STATUS_PAUSED - OGG_STATUS_EOF -> player stopped by End Of File - - */ - +/**************************************************************************** + * StatusOgg + * + * Returns the Ogg player's status + * returns: + * OGG_STATUS_RUNNING + * OGG_STATUS_ERR -> not initialized + * OGG_STATUS_PAUSED + * OGG_STATUS_EOF -> player stopped by End Of File + ***************************************************************************/ int StatusOgg(); -/*------------------------------------------------------------------------------------------------------------------------------------------------------*/ - -/* void SetVolumeOgg(int volume); - - Set the Ogg playing volume. - NOTE: it change the volume of voice 0 (used for the Ogg player) - - -- Params --- - - volume: 0 to 255 (max) - - */ - +/**************************************************************************** + * SetVolumeOgg + * + * Sets the Ogg playback volume (0 to 255 (max)) + ***************************************************************************/ void SetVolumeOgg(int volume); -/*------------------------------------------------------------------------------------------------------------------------------------------------------*/ - -/* s32 GetTimeOgg(); - - Return the Ogg time from the starts of the file - - -- Params --- - - return: 0 -> Ok or error condition (you must ignore this value) - >0 -> time in milliseconds from the starts - - */ - +/**************************************************************************** + * GetTimeOgg + * + * Gets current Ogg position + * returns -1 on error, or the time in milliseconds from the start + ***************************************************************************/ s32 GetTimeOgg(); -/*------------------------------------------------------------------------------------------------------------------------------------------------------*/ - -/* void SetTimeOgg(s32 time_pos); - - Set the time position - - NOTE: The file is closed by the player when you call PlayOgg(), StopOgg() or if it fail. - - -- Params --- - - time_pos: time position in the file (in milliseconds). For example, use 30000 to advance 30 seconds - - */ - +/**************************************************************************** + * SetTimeOgg + * + * Sets the time position + * time_pos: time position (in milliseconds) to advance + ***************************************************************************/ void SetTimeOgg(s32 time_pos); -/*------------------------------------------------------------------------------------------------------------------------------------------------------*/ - #ifdef __cplusplus } #endif #endif - -#endif