tetrees/Plugins/Wwise/ThirdParty/include/AK/SoundEngine/Common/IAkStreamMgr.h

/*******************************************************************************
The content of this file includes portions of the AUDIOKINETIC Wwise Technology
released in source code form as part of the SDK installer package.

Commercial License Usage

Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
may use this file in accordance with the end user license agreement provided 
with the software or, alternatively, in accordance with the terms contained in a
written agreement between you and Audiokinetic Inc.

Apache License Usage

Alternatively, this file may be used under the Apache License, Version 2.0 (the 
"Apache License"); you may not use this file except in compliance with the 
Apache License. You may obtain a copy of the Apache License at 
http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed
under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
the specific language governing permissions and limitations under the License.

  Copyright (c) 2023 Audiokinetic Inc.
*******************************************************************************/

/// \file 
/// Defines the API of Audiokinetic's I/O streaming solution.

#ifndef _IAK_STREAM_MGR_H_
#define _IAK_STREAM_MGR_H_

#include <AK/SoundEngine/Common/AkMemoryMgr.h>

//-----------------------------------------------------------------------------
// Defines. 
//-----------------------------------------------------------------------------

/// \name Profiling string lengths.
//@{
#define AK_MONITOR_STREAMNAME_MAXLENGTH    (64)
#define AK_MONITOR_DEVICENAME_MAXLENGTH    (16)
//@}
 
//-----------------------------------------------------------------------------
// Enums.
//-----------------------------------------------------------------------------

/// Stream status.
enum AkStmStatus
{
    AK_StmStatusIdle           	= 0,    	///< The stream is idle
    AK_StmStatusCompleted      	= 1,    	///< Operation completed / Automatic stream reached end
    AK_StmStatusPending        	= 2,    	///< Operation pending / The stream is waiting for I/O
    AK_StmStatusCancelled      	= 3,		///< Operation cancelled
    AK_StmStatusError          	= 4     	///< The low-level I/O reported an error
};

/// Move method for position change. 
/// \sa
/// - AK::IAkStdStream::SetPosition()
/// - AK::IAkAutoStream::SetPosition()
enum AkMoveMethod
{
    AK_MoveBegin               	= 0,    	///< Move offset from the start of the stream
    AK_MoveCurrent             	= 1,    	///< Move offset from the current stream position
    AK_MoveEnd                 	= 2     	///< Move offset from the end of the stream
};

/// File open mode.
enum AkOpenMode
{
    AK_OpenModeRead				= 0,		///< Read-only access
    AK_OpenModeWrite		    = 1,		///< Write-only access (opens the file if it already exists)
    AK_OpenModeWriteOvrwr	    = 2,		///< Write-only access (deletes the file if it already exists)
    AK_OpenModeReadWrite	    = 3	    	///< Read and write access
};

/// File system flags for file descriptors mapping.
struct AkFileSystemFlags
{
	AkFileSystemFlags()
		: uCacheID( AK_INVALID_FILE_ID ), uDirectoryHash( AK_INVALID_UNIQUE_ID ) {}

	AkFileSystemFlags( AkUInt32 in_uCompanyID, AkUInt32 in_uCodecID, AkUInt32 in_uCustomParamSize, void * in_pCustomParam, bool in_bIsLanguageSpecific, AkFileID in_uCacheID )
		: uCompanyID( in_uCompanyID )
		, uCodecID( in_uCodecID )
		, uCustomParamSize( in_uCustomParamSize )
		, pCustomParam( in_pCustomParam )
		, bIsLanguageSpecific( in_bIsLanguageSpecific )
		, uCacheID( in_uCacheID )
		, uNumBytesPrefetch( 0 )
		, uDirectoryHash( AK_INVALID_UNIQUE_ID ) {}

    AkUInt32            uCompanyID;         ///< Company ID (Wwise uses AKCOMPANYID_AUDIOKINETIC, defined in AkTypes.h, for soundbanks and standard streaming files, and AKCOMPANYID_AUDIOKINETIC_EXTERNAL for streaming external sources).
    AkUInt32            uCodecID;           ///< File/codec type ID (defined in AkTypes.h)
    AkUInt32            uCustomParamSize;   ///< Size of the custom parameter
    void *              pCustomParam;       ///< Custom parameter
    bool                bIsLanguageSpecific;///< True when the file location depends on language
	bool                bIsAutomaticStream;	///< True when the file is opened to be used as an automatic stream. Note that you don't need to set it. 
											///< If you pass an AkFileSystemFlags to IAkStreamMgr CreateStd|Auto(), it will be set internally to the correct value.
	AkFileID			uCacheID;			///< Cache ID for caching system used by automatic streams. The user is responsible for guaranteeing unicity of IDs. 
											///< When set, it supersedes the file ID passed to AK::IAkStreamMgr::CreateAuto() (ID version). Caching is optional and depends on the implementation.
	AkUInt32			uNumBytesPrefetch;	///< Indicates the number of bytes from the beginning of the file that should be streamed into cache via a caching stream. This field is only relevant when opening caching streams via 
											///< AK::IAkStreamMgr::PinFileInCache() and AK::SoundEngine::PinEventInStreamCache().  When using AK::SoundEngine::PinEventInStreamCache(), 
											///< it is initialized to the prefetch size stored in the sound bank, but may be changed by the file location resolver, or set to 0 to cancel caching.
	AkUInt32            uDirectoryHash;     ///< If the implementation uses a hashed directory structure, this is the hash value that should be employed for determining the directory structure
};

/// Stream information.
/// \sa
/// - AK::IAkStdStream::GetInfo()
/// - AK::IAkAutoStream::GetInfo()
struct AkStreamInfo
{
    AkDeviceID          deviceID;           ///< Device ID
    const AkOSChar *	pszName;            ///< User-defined stream name (specified through AK::IAkStdStream::SetStreamName() or AK::IAkAutoStream::SetStreamName())
    AkUInt64            uSize;              ///< Total stream/file size in bytes
	bool				bIsOpen;			///< True when the file is open (implementations may defer file opening)
};

/// Automatic streams heuristics.
struct AkAutoStmHeuristics
{
    AkReal32            fThroughput;        ///< Average throughput in bytes/ms
    AkUInt32            uLoopStart;         ///< Set to the start of loop (byte offset from the beginning of the stream) for streams that loop, 0 otherwise
    AkUInt32            uLoopEnd;           ///< Set to the end of loop (byte offset from the beginning of the stream) for streams that loop, 0 otherwise
    AkUInt8				uMinNumBuffers;     ///< Minimum number of buffers if you plan to own more than one buffer at a time, 0 or 1 otherwise
                                            ///< \remarks You should always release buffers as fast as possible, therefore this heuristic should be used only when 
                                            ///< dealing with special contraints, like drivers or hardware that require more than one buffer at a time.\n
                                            ///< Also, this is only a heuristic: it does not guarantee that data will be ready when calling AK::IAkAutoStream::GetBuffer().
    AkPriority          priority;           ///< The stream priority. it should be between AK_MIN_PRIORITY and AK_MAX_PRIORITY (included).
};

/// Automatic streams buffer settings/constraints.
struct AkAutoStmBufSettings
{
    AkUInt32			uBufferSize;		///< Hard user constraint: When non-zero, forces the I/O buffer to be of size uBufferSize
											///< (overriding the device's granularity).
											///< Otherwise, the size is determined by the device's granularity.
    AkUInt32            uMinBufferSize;     ///< Soft user constraint: When non-zero, specifies a minimum buffer size
                                            ///< \remarks Ignored if uBufferSize is specified.
	AkUInt32            uBlockSize;  		///< Hard user constraint: When non-zero, buffer size will be a multiple of that number, and returned addresses will always be aligned on multiples of this value.
};

/// \name Profiling structures.
//@{

#pragma pack(push, 4)

/// Device descriptor.
struct AkDeviceDesc
{
    AkDeviceID          deviceID;           ///< Device ID
    bool                bCanWrite;          ///< Specifies whether or not the device is writable
    bool                bCanRead;           ///< Specifies whether or not the device is readable
    AkUtf16				szDeviceName[AK_MONITOR_DEVICENAME_MAXLENGTH];      ///< Device name
    AkUInt32            uStringSize;        ///< Device name string's size (number of characters)
};

/// Device descriptor.
struct AkDeviceData
{
	AkDeviceID          deviceID;           ///< Device ID
	AkUInt32			uMemSize;			///< IO memory pool size
	AkUInt32			uMemUsed;			///< IO memory pool used	
	AkUInt32			uAllocs;			///< Cumulative number of allocations
	AkUInt32			uFrees;				///< Cumulative number of deallocations
	AkUInt32			uPeakRefdMemUsed;			///< Memory peak since monitoring started
	AkUInt32			uUnreferencedCachedBytes;	///< IO memory that is cached but is not currently used for active streams.
	AkUInt32			uGranularity;		///< IO memory pool block size
	AkUInt32			uNumActiveStreams;	///< Number of streams that have been active in the previous frame
	AkUInt32			uTotalBytesTransferred;			///< Number of bytes transferred, including cached transfers
	AkUInt32			uLowLevelBytesTransferred;		///< Number of bytes transferred exclusively via low-level
	AkReal32			fAvgCacheEfficiency;			///< Total bytes from cache as a percentage of total bytes. 
	AkUInt32			uNumLowLevelRequestsCompleted;	///< Number of low-level transfers that have completed in the previous monitoring frame
	AkUInt32			uNumLowLevelRequestsCancelled;	///< Number of low-level transfers that were cancelled in the previous monitoring frame
	AkUInt32			uNumLowLevelRequestsPending;	///< Number of low-level transfers that are currently pending
	AkUInt32			uCustomParam;		///< Custom number queried from low-level IO.
	AkUInt32			uCachePinnedBytes;  ///< Number of bytes that can be pinned into cache.
};

/// Stream general information.
struct AkStreamRecord
{
    AkUInt32            uStreamID;          ///< Unique stream identifier
    AkDeviceID          deviceID;           ///< Device ID
    AkUtf16				szStreamName[AK_MONITOR_STREAMNAME_MAXLENGTH];       ///< Stream name
    AkUInt32            uStringSize;        ///< Stream name string's size (number of characters)
    AkUInt64            uFileSize;          ///< File size
	AkUInt32			uCustomParamSize;	///< File descriptor's uCustomParamSize
    AkUInt32			uCustomParam;		///< File descriptor's pCustomParam (on 32 bits)
    bool                bIsAutoStream;      ///< True for auto streams
	bool				bIsCachingStream;	///< True for caching streams
};

/// Stream statistics.
struct AkStreamData
{
    AkUInt32            uStreamID;          ///< Unique stream identifier
    // Status (replace)
    AkUInt32            uPriority;          ///< Stream priority
	AkUInt64            uFilePosition;      ///< Current position
    AkUInt32            uTargetBufferingSize;		///< Total stream buffer size (specific to IAkAutoStream)
    AkUInt32            uVirtualBufferingSize;		///< Size of available data including requested data (specific to IAkAutoStream)
	AkUInt32            uBufferedSize;				///< Size of available data (specific to IAkAutoStream)
	AkUInt32            uNumBytesTransfered;		///< Transfered amount since last query (Accumulate/Reset)
	AkUInt32            uNumBytesTransferedLowLevel;///< Transfered amount (from low-level IO only) since last query (Accumulate/Reset)
	AkUInt32            uMemoryReferenced;			///< Amount of streaming memory referenced by this stream
	AkReal32			fEstimatedThroughput;		///< Estimated throughput heuristic
	bool				bActive;			///< True if this stream has been active (that is, was ready for I/O or had at least one pending I/O transfer, uncached or not) in the previous frame
};

#pragma pack(pop)

//@}

namespace AK
{
    /// \name Profiling interfaces.
    //@{
    
    /// Profiling interface of streams.
	/// \akwarning
	/// The functions in this interface are not thread-safe, unless stated otherwise.
	/// \endakwarning
    class IAkStreamProfile
    {
    protected:
        /// Virtual destructor on interface to avoid warnings.
		virtual ~IAkStreamProfile(){}

	public:
		/// Returns the stream's record (once).
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void    GetStreamRecord( 
            AkStreamRecord & out_streamRecord   ///< Returned stream record interface
            ) = 0;

        /// Returns the stream's statistics (every profile frame).
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void    GetStreamData(
            AkStreamData &   out_streamData     ///< Returned periodic stream data interface
            ) = 0;

        /// Query the stream's "new" flag.
        /// \return True, until AK::IAkStreamProfile::ClearNew() is called.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual bool    IsNew() = 0;

        /// Resets the stream's "new" flag.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void    ClearNew() = 0;
    };


    /// Profiling interface of high-level I/O devices.
	/// \akwarning
	/// The functions in this interface are not thread-safe, unless stated otherwise.
	/// \endakwarning
    class IAkDeviceProfile
    {
    protected:
    	/// Virtual destructor on interface to avoid warnings.
		virtual ~IAkDeviceProfile(){}

	public:

		/// Notify device when monitor sampling starts.
		virtual void	OnProfileStart() = 0;

		/// Notify device when monitor sampling ends.
		virtual void	OnProfileEnd() = 0;

		/// Query the device's description (once).
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void    GetDesc(
            AkDeviceDesc &  out_deviceDesc      ///< Device descriptor.
            ) = 0;

		/// Query the device's statistics (at every profiling frame).
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void    GetData(
            AkDeviceData &  out_deviceData		///< Device data.
            ) = 0;

        /// Query the device's "new" flag.
        /// \return True, until ClearNew() is called.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual bool    IsNew() = 0;

        /// Resets the device's "new" flag.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void    ClearNew() = 0;

        /// Get the number of streams currently associated with that device.
        /// \return The number of streams
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AkUInt32 GetNumStreams() = 0;

        /// Get a stream profile, for a specified stream index.
        /// \remarks GetStreamProfile() refers to streams by index, which must honor the call to AK::IAkDeviceProfile::GetNumStreams().
		/// \sa
		/// - \ref streamingdevicemanager
        virtual IAkStreamProfile * GetStreamProfile( 
			AkUInt32    in_uStreamIndex     ///< Stream index: [0,numStreams[
            ) = 0;
    };

    /// Profiling interface of the Stream Manager.
	/// \akwarning
	/// The functions in this interface are not thread-safe, unless stated otherwise.
	/// \endakwarning
    class IAkStreamMgrProfile
    {
    protected:
    	/// Virtual destructor on interface to avoid warnings.
		virtual ~IAkStreamMgrProfile(){}
		
	public:
        /// Start profile monitoring.
        /// \return AK_Success if successful, AK_Fail otherwise.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT StartMonitoring() = 0;

        /// Stop profile monitoring.
		/// \sa
		/// - \ref streamingdevicemanager
	    virtual void     StopMonitoring() = 0;
        
        /// Device enumeration.
        /// \return The number of devices.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AkUInt32 GetNumDevices() = 0;

        /// Get a device profile for a specified device index.
        /// \remarks GetDeviceProfile() refers to devices by index, which must honor the call to AK::IAkStreamMgrProfile::GetNumDevices().
        /// \remarks The device index is not the same as the device ID (AkDeviceID).
		/// \sa
		/// - \ref streamingdevicemanager
        virtual IAkDeviceProfile * GetDeviceProfile( 
			AkUInt32    in_uDeviceIndex     ///< Device index: [0,numDevices[
            ) = 0;
    };
    //@}

    /// \name High-level streams API.
    //@{

    /// Interface of standard streams. Used as a handle to a standard stream. Has methods for 
    /// stream control. Obtained through the Stream Manager's AK::IAkStreamMgr::CreateStd() method.
	/// \akwarning
	/// The functions in this interface are not thread-safe, unless stated otherwise.
	/// \endakwarning
    class IAkStdStream
    {
    protected:
       	/// Virtual destructor on interface to avoid warnings.
		virtual ~IAkStdStream(){}

	public:
        /// \name Stream management and settings.
        //@{
        /// Close the stream. The object is destroyed and the interface becomes invalid.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void      Destroy() = 0;

        /// Get information about a stream.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void      GetInfo(
            AkStreamInfo &	out_info			///< Returned stream info
            ) = 0;

		/// Returns a unique cookie for a given stream.
		/// The default implementation of the Stream Manager returns its file descriptor (see AkStreamMgrModule.h).
		virtual void * GetFileDescriptor() = 0;

        /// Give the stream a name (appears in the Wwise Profiler).
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT  SetStreamName(
            const AkOSChar *	in_pszStreamName    ///< Stream name
            ) = 0;

        /// Get the I/O block size.
		/// \remark Queries the low-level I/O, by calling AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize() with the
        /// stream's file descriptor.
        /// \return The block size, in bytes.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AkUInt32  GetBlockSize() = 0;   
        //@}

        /// \name I/O operations.
        //@{
        
        /// Schedule a read request.
        /// \warning Use only with a multiple of the block size, queried via AK::IAkStdStream::GetBlockSize().
        /// \remarks If the call is asynchronous (in_bWait = false), wait until AK::IAkStdStream::GetStatus() stops returning AK_StmStatusPending.
        /// \return AK_Success if the operation was successfully scheduled (but not necessarily completed)
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT Read(
            void *          in_pBuffer,         ///< User buffer address 
            AkUInt32        in_uReqSize,        ///< Requested read size
            bool            in_bWait,           ///< Block until the operation is complete
            AkPriority      in_priority,        ///< Heuristic: operation priority
            AkReal32        in_fDeadline,       ///< Heuristic: operation deadline (ms)
            AkUInt32 &      out_uSize           ///< The size that was actually read
            ) = 0;

        /// Schedule a write request.
        /// \warning Use only with a multiple of the block size, queried via AK::IAkStdStream::GetBlockSize().
        /// \remarks If the call is asynchronous (in_bWait = false), wait until GetStatus() stops returning AK_StmStatusPending.
        /// \return AK_Success if the operation was successfully scheduled
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT Write(
            void *          in_pBuffer,         ///< User buffer address
            AkUInt32        in_uReqSize,        ///< Requested write size
            bool            in_bWait,           ///< Block until the operation is complete
            AkPriority      in_priority,        ///< Heuristic: operation priority
            AkReal32        in_fDeadline,       ///< Heuristic: operation deadline (ms)
            AkUInt32 &      out_uSize           ///< The size that was actually written
            ) = 0;

        /// Get the current stream position.
        /// \remarks If an operation is pending, there is no guarantee that the position was queried before (or after) the operation was completed.
        /// \return The current stream position
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AkUInt64 GetPosition( 
            bool *          out_pbEndOfStream   ///< Returned end-of-stream flag, only for streams opened with AK_OpenModeRead (can pass NULL)
            ) = 0;

        /// Set the stream position. Modifies the position for the next read/write operation.
        /// \warning No operation should be pending.
        /// \remarks The new position will snap to the lowest block boundary.
        /// \return AK_Success if the stream position was changed
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT SetPosition(
            AkInt64         in_iMoveOffset,     ///< Seek offset
            AkMoveMethod    in_eMoveMethod,     ///< Seek method, from the beginning, end, or current file position
            AkInt64 *       out_piRealOffset    ///< The actual seek offset may differ from the expected value when the block size is bigger than 1.
                                                ///< In that case, the seek offset floors to the sector boundary. Can pass NULL.
            ) = 0;

        /// Cancel the current operation.
        /// \remarks When it returns, the caller is guaranteed that no operation is pending.
        /// \remarks This method can block the caller for the whole duration of the I/O operation, if the request was already posted.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void Cancel() = 0;

        //@}

        /// \name Access to data and status.
        //@{
        /// Get user data (and accessed size).
        /// \return The address of data provided by user
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void *   GetData( 
            AkUInt32 &      out_uSize           ///< Size actually read or written
            ) = 0;

        /// Get the stream's status.
        /// \return The stream status.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AkStmStatus GetStatus() = 0;  

        /// Block and wait for a pending read to finish, and return the current status of the stream.
        /// This will return immediately if the status is not pending.
        /// \return The stream status.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AkStmStatus WaitForPendingOperation() = 0;

        //@}
    };


    /// Interface of automatic streams. It is used as a handle to a stream, 
    /// I/O operations are triggered from here. 
    /// Obtained through the Stream Manager's AK::IAkStreamMgr::CreateAuto() method.
	/// \akwarning
	/// The functions in this interface are not thread-safe, unless stated otherwise.
	/// \endakwarning
	/// \sa
	/// - \ref streamingdevicemanager
    class IAkAutoStream 
    {
    protected:
    	/// Virtual destructor on interface to avoid warnings.
		virtual ~IAkAutoStream(){}

	public:
        /// \name Stream management, settings access, and run-time change.
        //@{
        /// Close the stream. The object is destroyed and the interface becomes invalid.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void      Destroy() = 0;

        /// Get information about the stream.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void      GetInfo(
            AkStreamInfo &      out_info        ///< Returned stream info
            ) = 0;

		/// Returns a unique cookie for a given stream.
		/// The default implementation of the Stream Manager returns its file descriptor (see AkStreamMgrModule.h).
		virtual void * GetFileDescriptor() = 0;

        /// Get the stream's heuristics.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void      GetHeuristics(
            AkAutoStmHeuristics & out_heuristics///< Returned stream heuristics
            ) = 0;

        /// Run-time change of the stream's heuristics.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT  SetHeuristics(
            const AkAutoStmHeuristics & in_heuristics   ///< New stream heuristics
            ) = 0;

		/// Run-time change of the stream's minimum buffer size that can be handed out to client
		/// in GetBuffer() (except the last buffer at the end of file).
		/// Corresponds to the uMinBufferSize field of the AkAutoStmBufSettings passed to CreateAuto().
		/// \sa
		/// - AkAutoStmBufSettings
		/// - \ref streamingdevicemanager
		virtual AKRESULT  SetMinimalBufferSize(
			AkUInt32		in_uMinBufferSize	///< Minimum buffer size that can be handed out to client.
			) = 0;

		/// Set the minimum size to buffer ahead in an automated stream.
		///
		/// This function was made available to allow systems that cannot only rely on AkAutoStmHeuristics::fThroughput to predict what will be the best target size of an automatic stream.
		/// The system will predict the minimum size to buffer and will consider this value as the minimal size to be the target.
		/// \sa
		/// - AkAutoStmBufSettings
		/// - \ref streamingdevicemanager
		/// - \ref AkAutoStmHeuristics
		virtual AKRESULT  SetMinTargetBufferSize(
			AkUInt32		in_uMinTargetBufferSize	///< Minimum size to buffer ahead in an automated stream. (in bytes)
		) = 0;

        /// Give the stream a name (appears in the Wwise profiler).
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT  SetStreamName(
            const AkOSChar *	in_pszStreamName    ///< Stream name
            ) = 0;

        /// Get the I/O block size.
		/// \remark Queries the actual low-level I/O device, by calling AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize() with the
        /// stream's file descriptor.
        /// \return The block size (in bytes)
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AkUInt32  GetBlockSize() = 0;

		/// Get the amount of buffering that the stream has. 
		/// The buffering is defined as the number of bytes that the stream has buffered, excluding the number
		/// of bytes that is currently granted to the user (with GetBuffer()).
		/// \remark The returned value corresponds to the buffering status at that moment, and does not even 
		/// guarantee that it will not shrink.
		/// \return 
		/// - AK_DataReady: Some data has been buffered (out_uNumBytesAvailable is greater than 0).
		/// - AK_NoDataReady: No data is available, and the end of file has not been reached.
		/// - AK_NoMoreData: Some or no data is available, but the end of file has been reached. The stream will not buffer any more data.
		/// - AK_Fail: The stream is invalid due to an I/O error.
		virtual AKRESULT QueryBufferingStatus( 
			AkUInt32 & out_uNumBytesAvailable	///< Number of bytes available in the stream's buffer(s).
			) = 0;

		/// Returns the target buffering size based on the throughput heuristic.
		/// \return
		/// Target buffering length expressed in bytes. 
		virtual AkUInt32 GetNominalBuffering() = 0;

        //@}

        /// \name Stream operations.
        //@{
        
        /// Start the automatic scheduling.
        /// \return AK_Success if the automatic scheduling was started successfully
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT Start() = 0;

        /// Stop the automatic scheduling.
        /// \return AK_Success if the automatic scheduling was stopped successfully.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT Stop() = 0;

        /// Get the stream's position.
        /// \remarks The stream position is the position seen by the user, not the position of the file
        /// already streamed into the Stream Manager's memory. The stream position is updated when buffers 
        /// are released, using AK::IAkAutoStream::ReleaseBuffer().
        /// \return The file position in bytes of the beginning of the first buffer owned by the user. 
		/// If the user does not own a buffer, it returns the position of the beginning of the buffer that 
		/// would be returned from a call to AK::IAkAutoStream::GetBuffer().
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AkUInt64 GetPosition( 
            bool *          out_pbEndOfStream   ///< Returned end-of-stream flag (can pass NULL)
            ) = 0;  

        /// Set the stream's position. 
        /// The next call to AK::IAkAutoStream::GetBuffer() will grant data that corresponds to the position specified here.
        /// \remarks Data already streamed into the Stream Manager's memory might be flushed.
        /// \remarks The new position will round down to the low-level I/O block size.
        /// \return AK_Success if the resulting position is valid
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT SetPosition(
            AkInt64         in_iMoveOffset,     ///< Seek offset
            AkMoveMethod    in_eMoveMethod,     ///< Seek method, from the beginning, end or current file position
            AkInt64 *       out_piRealOffset    ///< The actual seek offset may differ from the expected value when the low-level's block size is greater than 1.
                                                ///< In that case, the real absolute position rounds down to the block boundary. Can pass NULL.
            ) = 0;

        //@}


        /// \name Data/status access.
        //@{

        /// Get data from the Stream Manager buffers.
        /// \remarks Grants a buffer if data is available. Each successful call to this method returns a new 
        /// buffer of data, at the current stream position.
        /// Buffers should be released as soon as they are not needed, using AK::IAkAutoStream::ReleaseBuffer().
        /// \aknote AK::IAkAutoStream::ReleaseBuffer() does not take any argument, because it releases buffers in order. \endaknote
        /// \return
        ///     - AK_DataReady     : the buffer was granted
		///     - AK_NoDataReady   : the buffer is not granted yet (never happens when called with in_bWait flag)
        ///     - AK_NoMoreData    : the buffer was granted but reached end of file (next call will return with size 0)
        ///     - AK_Fail          : there was an I/O error
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT GetBuffer(
            void *&         out_pBuffer,        ///< Returned address of granted data space
            AkUInt32 &      out_uSize,          ///< Returned size of granted data space
            bool            in_bWait            ///< Block until data is ready
            ) = 0;

        /// Release buffer granted through GetBuffer(). Buffers are released in order.
        /// \return AK_Success if a valid buffer was released, AK_Fail if the user did not own any buffer.
		/// \note To implementers: Clients like the sound engine may release buffers until this function returns AK_Fail.
		/// Failing to release a buffer should not be considered as a fatal error.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT ReleaseBuffer() = 0;
        //@}
    };

    //@}


    /// Interface of the Stream Manager.
	/// \akwarning
	/// The functions in this interface are not thread-safe, unless stated otherwise.
	/// \endakwarning
    class IAkStreamMgr
    {
    protected:
    	/// Virtual destructor on interface to avoid warnings.
		virtual ~IAkStreamMgr(){}
		
	public:
        /// Global access to singleton.
        /// \return The interface of the global Stream Manager
		/// \sa
		/// - \ref streamingdevicemanager
        inline static IAkStreamMgr * Get()
        {
            return m_pStreamMgr;
        }

        /// Destroy the Stream Manager.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual void     Destroy() = 0;


        /// \name Profiling.
        //@{
        /// Get the profiling interface.
        /// \return The interface of the Stream Manager profiler
        virtual IAkStreamMgrProfile * GetStreamMgrProfile() = 0;
        //@}


        /// \name Stream creation interface.
        //@{
        
        // Standard stream creation methods.

        /// Create a standard stream (string overload).
        /// \return AK_Success if the stream was created successfully
        /// \remarks The string overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT CreateStd(
            const AkOSChar*     in_pszFileName,     ///< Application-defined string (title only, or full path, or code...)
            AkFileSystemFlags * in_pFSFlags,        ///< Special file system flags. Can pass NULL
            AkOpenMode          in_eOpenMode,       ///< Open mode (read, write, ...)
            IAkStdStream *&     out_pStream,		///< Returned interface to a standard stream. If the function does not return AK_Success, this pointer is left untouched.
			bool				in_bSyncOpen		///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
            ) = 0;

        /// Create a standard stream (ID overload).
        /// \return AK_Success if the stream was created successfully
        /// \remarks The ID overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT CreateStd(
            AkFileID            in_fileID,          ///< Application-defined ID
            AkFileSystemFlags * in_pFSFlags,        ///< Special file system flags (can pass NULL)
            AkOpenMode          in_eOpenMode,       ///< Open mode (read, write, ...)
            IAkStdStream *&     out_pStream,		///< Returned interface to a standard stream. If the function does not return AK_Success, this pointer is left untouched.
			bool				in_bSyncOpen		///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
            ) = 0;

        
        // Automatic stream create methods.

        /// Create an automatic stream (string overload).
        /// \return AK_Success if the stream was created successfully
        /// \remarks The stream needs to be started explicitly with AK::IAkAutoStream::Start().
		/// \remarks The string overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT CreateAuto(
            const AkOSChar*             in_pszFileName,     ///< Application-defined string (title only, or full path, or code...)
            AkFileSystemFlags *         in_pFSFlags,        ///< Special file system flags (can pass NULL)
            const AkAutoStmHeuristics & in_heuristics,      ///< Streaming heuristics
            AkAutoStmBufSettings *      in_pBufferSettings, ///< Stream buffer settings (it is recommended to pass NULL in order to use the default settings)
            IAkAutoStream *&            out_pStream,		///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched.
			bool						in_bSyncOpen		///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
            ) = 0;

        /// Create an automatic stream (ID overload).
        /// \return AK_Success if the stream was created successfully
        /// \remarks The stream needs to be started explicitly with IAkAutoStream::Start().
        /// \remarks The ID overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
		/// \sa
		/// - \ref streamingdevicemanager
        virtual AKRESULT CreateAuto(
            AkFileID                    in_fileID,          ///< Application-defined ID
            AkFileSystemFlags *         in_pFSFlags,        ///< Special file system flags (can pass NULL)
            const AkAutoStmHeuristics & in_heuristics,      ///< Streaming heuristics
            AkAutoStmBufSettings *      in_pBufferSettings, ///< Stream buffer settings (it is recommended to pass NULL to use the default settings)
			IAkAutoStream *&            out_pStream,		///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched.
			bool						in_bSyncOpen		///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
            ) = 0;

		/// Create an automatic stream (in-memory buffer overload).
        ///
        /// This overload differs largely from CreateAuto() implementations, which are file based.
        /// This version is provided with a memory space and the resulting automatic stream will simply 
        /// return the memory space in a similar fashion, but without the need to perform any actual file operations.
        ///
        /// If you are in the process of implementing your own IAkStreamMgr object, 
        /// consider using the initial implementation from `\\SDK\\source\\StreamManager\\Common\\AkStreamMgr.cpp`.
        ///
		/// \return AK_Success if the stream was created successfully
		/// \remarks The stream needs to be started explicitly with IAkAutoStream::Start().
		/// \sa
		/// - \ref streamingdevicemanager
		virtual AKRESULT CreateAuto(
			void *                      in_pBuffer,         ///< Pointer to the memory area containing stream data
			AkUInt64                    in_uSize,           ///< Size of the memory area containing stream data
			const AkAutoStmHeuristics & in_heuristics,      ///< Streaming heuristics
			IAkAutoStream *&            out_pStream         ///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched.
			) = 0;

		/// Start streaming the first "in_pFSFlags->uNumBytesPrefetch" bytes of the file with id "in_fileID" into cache.  The stream will be scheduled only after
		/// all regular streams (not file caching streams) are serviced.  The file will stay cached until either the UnpinFileInCache is called,
		/// or the limit as set by uMaxCachePinnedBytes is reached and another higher priority file (in_uPriority) needs the space.  
		/// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API. 
		///		Using PinFileInCache() directly does not allow users to take advantage of sound bank data.  The file and the number of bytes they wish to cache must be explicitly specified.
		/// 
		/// \sa
		/// - \ref streamingdevicemanager
		/// - AK::SoundEngine::PinEventInStreamCache
		/// - AK::SoundEngine::UnpinEventInStreamCache
		/// - AkFileSystemFlags
		virtual AKRESULT PinFileInCache(
			AkFileID                    in_fileID,          ///< Application-defined ID
			AkFileSystemFlags *         in_pFSFlags,        ///< Special file system flags (can NOT pass NULL)
			AkPriority					in_uPriority		///< Stream caching priority.  Note: Caching requests only get serviced after all regular streaming requests.
			) = 0;

		/// Un-pin a file that has been previouly pinned into cache.  This function must be called once for every call to PinFileInCache() with the same file id.
		/// The file may still remain in stream cache after this is called, until the memory is reused by the streaming memory manager in accordance with to its 
		/// cache management algorithm.
		/// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API. 
		///		Using UnpinFileInCache() directly does not allow users to take advantage of sound bank data.  The file must be explicitly specified.
		/// \sa
		/// - \ref streamingdevicemanager
		/// - AK::SoundEngine::PinEventInStreamCache
		/// - AK::SoundEngine::UnpinEventInStreamCache
		virtual AKRESULT UnpinFileInCache(
			AkFileID                    in_fileID,          	///< Application-defined ID
			AkPriority					in_uPriority 		///< Priority of stream that you are unpinning
			) = 0;
		
		/// Update the priority of the caching stream.  Higher priority streams will be serviced before lower priority caching streams, and will be more likely to stay in 
		/// memory if the cache pin limit as set by "uMaxCachePinnedBytes" is reached.
		/// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API. 
		///		Using UpdateCachingPriority() directly does not allow users to take advantage of sound bank data.  The file must be explicitly specified.
		/// \sa
		/// - \ref streamingdevicemanager
		/// - AK::SoundEngine::PinEventInStreamCache
		/// - AK::SoundEngine::UnpinEventInStreamCache
		virtual AKRESULT UpdateCachingPriority(
			AkFileID                    in_fileID,			///< Application-defined ID
			AkPriority					in_uPriority, 		///< Priority
			AkPriority					in_uOldPriority 		///< Old priority
			) = 0;
		
		/// Return information about a file that has been pinned into cache.
		/// Retrieves the percentage of the requested buffer size that has been streamed in and stored into stream cache, and whether 
		/// the cache pinned memory limit is preventing this buffer from filling.
		virtual AKRESULT GetBufferStatusForPinnedFile( 
			AkFileID in_fileID,								///< Application-defined ID
			AkReal32& out_fPercentBuffered,					///< Percentage of buffer full (out of 100)
			bool& out_bCacheFull							///< Set to true if the rest of the buffer can not fit into the cache-pinned memory limit.
			) = 0;

		/// Make a memory stream point to a new area in memory, otherwise keeping the exact same state.
		virtual AKRESULT RelocateMemoryStream(
			IAkAutoStream * in_pStream,                     ///< The stream to relocate. Must be a stream created with the memory overload of CreateAutoStm.
			AkUInt8 * in_pNewStart                          ///< The new area in memory to point to
		) = 0;

		//@}

    protected:
        /// Definition of the global pointer to the interface of the Stream Manager singleton.
		/// \sa
		/// - \ref streamingdevicemanager
        static AKSOUNDENGINE_API IAkStreamMgr * m_pStreamMgr;
    };

}
#endif //_IAK_STREAM_MGR_H_