Engine directory for ticket #1

Engine/source/sfx/sfxBuffer.h

@@ -0,0 +1,236 @@
+//-----------------------------------------------------------------------------
+// Copyright (c) 2012 GarageGames, LLC
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to
+// deal in the Software without restriction, including without limitation the
+// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+// sell copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+// IN THE SOFTWARE.
+//-----------------------------------------------------------------------------
+
+#ifndef _SFXBUFFER_H_
+#define _SFXBUFFER_H_
+
+#ifndef _REFBASE_H_
+#include "core/util/refBase.h"
+#endif
+
+#ifndef _TSIGNAL_H_
+#include "core/util/tSignal.h"
+#endif
+
+#ifndef _TSTREAM_H_
+#include "core/stream/tStream.h"
+#endif
+
+#ifndef _SFXCOMMON_H_
+#include "sfx/sfxCommon.h"
+#endif
+
+#ifndef _THREADSAFEREFCOUNT_H_
+#include "platform/threads/threadSafeRefCount.h"
+#endif
+
+
+class SFXStream;
+class SFXDescription;
+class SFXVoice;
+
+namespace SFXInternal {
+   class SFXStreamPacket;
+   class SFXAsyncStream;
+   class SFXAsyncQueue;
+   void PurgeDeadBuffers();
+}
+
+
+/// The buffer interface hides the details of how the device holds sound data for playback.
+///
+/// A sound buffer may either be loaded once completely and then played as needed or it may
+/// be progressively streamed from an SFXStream.  In the latter case, there can only be a single
+/// voice tied to the buffer.
+///
+/// @note SFXDevice is the last instance when it comes to ownership
+///   of SFXBuffers.  If the SFXDevice goes away, it will take all
+///   SFXBuffers with it, regardless of whether there are still strong
+///   refs to it.  Use StrongWeakRefPtrs to keep pointers to
+///   SFXBuffers!
+///
+/// @see SFXStream
+class SFXBuffer :    public StrongRefBase,
+                     public IPolled, // SFXBuffers are periodically updated on the SFX thread.
+                     public IOutputStream< SFXInternal::SFXStreamPacket* > // Interface for writing sound data to the buffer.
+{
+      friend class SFXVoice; // mUniqueVoice
+      friend void SFXInternal::PurgeDeadBuffers(); // dtor
+
+   public:
+
+      typedef void Parent;
+
+      /// Status indicators for sound buffers.
+      enum Status
+      {
+         STATUS_Null,      ///< Initial state.
+         STATUS_Loading,   ///< Buffer has requested data and is waiting for queue to fill up.
+         STATUS_Ready,     ///< Playback queue is fed and ready (non-stream buffers will stop at this state).
+         STATUS_Blocked,   ///< Queue is starved and playback thus held until further data is available (streaming buffers only).
+         STATUS_AtEnd,     ///< Buffer has read all its streaming data (streaming buffers only).
+      };
+
+      /// This signal is triggered from SFXBuffer's destructor so the sound system
+      /// can keep track of buffers being released on the device.
+      static Signal< void( SFXBuffer* ) > smBufferDestroyedSignal;
+
+   protected:
+
+      typedef ThreadSafeRef< SFXInternal::SFXAsyncStream > SFXAsyncStreamPtr;
+      typedef SFXInternal::SFXAsyncQueue* SFXAsyncQueuePtr;
+
+      /// Encapsulates the async I/O state of the sound buffer.
+      struct AsyncState : public ThreadSafeRefCount< AsyncState >
+      {
+         /// The sound packet stream.
+         SFXAsyncStreamPtr mStream;
+
+         /// The packet queue that feeds into the actual device buffer.
+         /// Only used for streaming buffers; non-streaming buffers directly receive
+         /// and upload sound packets without queuing.
+         SFXAsyncQueuePtr mQueue;
+
+         AsyncState();
+         AsyncState( SFXInternal::SFXAsyncStream* stream );
+         ~AsyncState();
+      };
+
+      typedef ThreadSafeRef< AsyncState > AsyncStatePtr;
+
+      /// Create a new buffer from @a stream using the parameters in @a description.
+      ///
+      /// @param stream Sound stream from which to read sound data into the buffer.
+      /// @param description Sound setup description.
+      /// @param createAsyncState If true, the asynchronous loading state for the buffer will be set up
+      ///   in the constructor.  This is mainly useful for the null device which creates dummy buffers that
+      ///   do not need the async state to be in place.  All other buffers do.
+      SFXBuffer( const ThreadSafeRef< SFXStream >& stream, SFXDescription* description, bool createAsyncState = true );
+      
+      /// Create a buffer with just a description.  This is used by devices who fully take over loading
+      /// and streaming.
+      SFXBuffer( SFXDescription* description );
+      
+      virtual ~SFXBuffer();
+
+      /// The buffer readiness status.
+      Status mStatus;
+      
+      /// The sound sample format used by the buffer.
+      SFXFormat mFormat;
+
+      /// Total playback time of the associated sound stream in milliseconds.
+      /// @note For streaming buffers, this will not correspond to the actual
+      ///   playtime of the device buffer.
+      U32 mDuration;
+
+      /// If true, this is a continuously streaming buffer.
+      bool mIsStreaming;
+      
+      /// For streaming buffers, tells whether the source stream loops.
+      bool mIsLooping;
+
+      /// If true, this buffer can only have a single SFXVoice attached.
+      bool mIsUnique;
+
+      /// If true, the buffer is dead and will be deleted.  Can't be in status
+      /// for synchronization reasons.
+      bool mIsDead;
+
+      /// Pointer to structure keeping the asynchronous I/O state of the buffer.
+      /// For non-streaming buffers, this is released as soon as all data is loaded.
+      ///
+      /// To allow seeking in streaming buffers even after playback has ended,
+      /// we do not release the async state of these buffers until the buffer is
+      /// actually released itself.  This allows to always access the associated
+      /// input stream.
+      ///
+      /// @note For devices that handle loading/streaming on their own, this will
+      ///   not be set.
+      AsyncStatePtr mAsyncState;
+
+      /// If this is a unique buffer (i.e. a streaming buffer), then this holds
+      /// the reference to the unique voice.
+      StrongWeakRefPtr< SFXVoice > mUniqueVoice;
+
+      /// Set the buffer status and trigger mOnStatusChange if the status changes.
+      /// @note Called on both the SFX update thread and the main thread.
+      void _setStatus( Status status );
+
+      /// Flush all queue state for this buffer on the device.
+      /// @note Called on the SFX update thread.
+      virtual void _flush() = 0;
+
+   public:
+
+      /// Signal that is triggered when the buffer status changes.
+      /// @note This signal is triggered on the same thread that the buffer update
+      ///   code runs on.
+      Signal< void( SFXBuffer* buffer, Status newStatus ) > mOnStatusChange;
+
+      /// @return The current buffer loading/queue status.
+      Status getStatus() const { return mStatus; }
+
+      /// @return The sound sample format used by the buffer.
+      const SFXFormat& getFormat() const { return mFormat; }
+
+      /// @return The total playback time of the buffer in milliseconds.
+      U32 getDuration() const { return mDuration; }
+
+      /// @return The total number of samples in the buffer.
+      U32 getNumSamples() const { return getFormat().getSampleCount( mDuration ); }
+
+      /// @return The number of bytes consumed by this sound buffer.
+      virtual U32 getMemoryUsed() const { return 0; }
+
+      /// @return True if the buffer does continuous sound streaming.
+      bool isStreaming() const { return mIsStreaming; }
+
+      /// @return True if the buffer is pending deletion.
+      bool isDead() const { return mIsDead; }
+
+      /// @return True if the buffer's packet queue is loaded and ready for playback.
+      bool isReady() const { return ( getStatus() == STATUS_Ready ); }
+
+      /// @return True if the buffer's packet queue is still loading.
+      bool isLoading() const { return ( getStatus() == STATUS_Loading ); }
+
+      /// @return True if the buffer's packet queue has been starved and is waiting for data.
+      bool isBlocked() const { return ( getStatus() == STATUS_Blocked ); }
+
+      /// @return True if the buffer has exhausted its source stream
+      bool isAtEnd() const { return ( getStatus() == STATUS_AtEnd ); }
+
+      /// @return True if the buffer can only have a single SFXVoice attached to it.
+      bool isUnique() const { return mIsUnique; }
+
+      /// Start the async request chain for the buffer.
+      void load();
+
+      // IPolled.
+      virtual bool update();
+
+      // WeakRefBase.
+      virtual void destroySelf();
+};
+
+#endif // _SFXBUFFER_H_