Wwise SDK 2022.1.4
_i_ak_stream_mgr_8h_source
Version
menu_open
link
Wwise SDK 2022.1.4
|
IAkStreamMgr.h
Go to the documentation of this file.
57 };
68 };
77 };
85 AkFileSystemFlags( AkUInt32 in_uCompanyID, AkUInt32 in_uCodecID, AkUInt32 in_uCustomParamSize, void * in_pCustomParam, bool in_bIsLanguageSpecific, AkFileID in_uCacheID )
95 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).
100 bool bIsAutomaticStream; ///< True when the file is opened to be used as an automatic stream. Note that you don't need to set it.
101 ///< If you pass an AkFileSystemFlags to IAkStreamMgr CreateStd|Auto(), it will be set internally to the correct value.
102 AkFileID uCacheID; ///< Cache ID for caching system used by automatic streams. The user is responsible for guaranteeing unicity of IDs.
103 ///< When set, it supersedes the file ID passed to AK::IAkStreamMgr::CreateAuto() (ID version). Caching is optional and depends on the implementation.
104 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
105 ///< AK::IAkStreamMgr::PinFileInCache() and AK::SoundEngine::PinEventInStreamCache(). When using AK::SoundEngine::PinEventInStreamCache(),
106 ///< 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.
107 AkUInt32 uDirectoryHash; ///< If the implementation uses a hashed directory structure, this is the hash value that should be employed for determining the directory structure
117 const AkOSChar * pszName; ///< User-defined stream name (specified through AK::IAkStdStream::SetStreamName() or AK::IAkAutoStream::SetStreamName())
126 AkUInt32 uLoopStart; ///< Set to the start of loop (byte offset from the beginning of the stream) for streams that loop, 0 otherwise
127 AkUInt32 uLoopEnd; ///< Set to the end of loop (byte offset from the beginning of the stream) for streams that loop, 0 otherwise
128 AkUInt8 uMinNumBuffers; ///< Minimum number of buffers if you plan to own more than one buffer at a time, 0 or 1 otherwise
129 ///< \remarks You should always release buffers as fast as possible, therefore this heuristic should be used only when
130 ///< dealing with special contraints, like drivers or hardware that require more than one buffer at a time.\n
131 ///< Also, this is only a heuristic: it does not guarantee that data will be ready when calling AK::IAkAutoStream::GetBuffer().
132 AkPriority priority; ///< The stream priority. it should be between AK_MIN_PRIORITY and AK_MAX_PRIORITY (included).
138 AkUInt32 uBufferSize; ///< Hard user constraint: When non-zero, forces the I/O buffer to be of size uBufferSize
141 AkUInt32 uMinBufferSize; ///< Soft user constraint: When non-zero, specifies a minimum buffer size
143 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.
170 AkUInt32 uUnreferencedCachedBytes; ///< IO memory that is cached but is not currently used for active streams.
176 AkUInt32 uNumLowLevelRequestsCompleted; ///< Number of low-level transfers that have completed in the previous monitoring frame
177 AkUInt32 uNumLowLevelRequestsCancelled; ///< Number of low-level transfers that were cancelled in the previous monitoring frame
178 AkUInt32 uNumLowLevelRequestsPending; ///< Number of low-level transfers that are currently pending
205 AkUInt32 uVirtualBufferingSize; ///< Size of available data including requested data (specific to IAkAutoStream)
208 AkUInt32 uNumBytesTransferedLowLevel;///< Transfered amount (from low-level IO only) since last query (Accumulate/Reset)
211 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
311 /// \remarks GetStreamProfile() refers to streams by index, which must honor the call to AK::IAkDeviceProfile::GetNumStreams().
348 /// \remarks GetDeviceProfile() refers to devices by index, which must honor the call to AK::IAkStreamMgrProfile::GetNumDevices().
388 /// The default implementation of the Stream Manager returns its file descriptor (see AkStreamMgrModule.h).
399 /// \remark Queries the low-level I/O, by calling AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize() with the
411 /// \warning Use only with a multiple of the block size, queried via AK::IAkStdStream::GetBlockSize().
412 /// \remarks If the call is asynchronous (in_bWait = false), wait until AK::IAkStdStream::GetStatus() stops returning AK_StmStatusPending.
413 /// \return AK_Success if the operation was successfully scheduled (but not necessarily completed)
426 /// \warning Use only with a multiple of the block size, queried via AK::IAkStdStream::GetBlockSize().
427 /// \remarks If the call is asynchronous (in_bWait = false), wait until GetStatus() stops returning AK_StmStatusPending.
441 /// \remarks If an operation is pending, there is no guarantee that the position was queried before (or after) the operation was completed.
446 bool * out_pbEndOfStream ///< Returned end-of-stream flag, only for streams opened with AK_OpenModeRead (can pass NULL)
457 AkMoveMethod in_eMoveMethod, ///< Seek method, from the beginning, end, or current file position
458 AkInt64 * out_piRealOffset ///< The actual seek offset may differ from the expected value when the block size is bigger than 1.
464 /// \remarks This method can block the caller for the whole duration of the I/O operation, if the request was already posted.
528 /// The default implementation of the Stream Manager returns its file descriptor (see AkStreamMgrModule.h).
557 /// 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.
558 /// The system will predict the minimum size to buffer and will consider this value as the minimal size to be the target.
564 AkUInt32 in_uMinTargetBufferSize ///< Minimum size to buffer ahead in an automated stream. (in bytes)
575 /// \remark Queries the actual low-level I/O device, by calling AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize() with the
583 /// The buffering is defined as the number of bytes that the stream has buffered, excluding the number
585 /// \remark The returned value corresponds to the buffering status at that moment, and does not even
590 /// - AK_NoMoreData: Some or no data is available, but the end of file has been reached. The stream will not buffer any more data.
620 /// already streamed into the Stream Manager's memory. The stream position is updated when buffers
623 /// If the user does not own a buffer, it returns the position of the beginning of the buffer that
632 /// The next call to AK::IAkAutoStream::GetBuffer() will grant data that corresponds to the position specified here.
641 AkInt64 * out_piRealOffset ///< The actual seek offset may differ from the expected value when the low-level's block size is greater than 1.
652 /// \remarks Grants a buffer if data is available. Each successful call to this method returns a new
654 /// Buffers should be released as soon as they are not needed, using AK::IAkAutoStream::ReleaseBuffer().
655 /// \aknote AK::IAkAutoStream::ReleaseBuffer() does not take any argument, because it releases buffers in order. \endaknote
658 /// - AK_NoDataReady : the buffer is not granted yet (never happens when called with in_bWait flag)
659 /// - AK_NoMoreData : the buffer was granted but reached end of file (next call will return with size 0)
670 /// \return AK_Success if a valid buffer was released, AK_Fail if the user did not own any buffer.
671 /// \note To implementers: Clients like the sound engine may release buffers until this function returns AK_Fail.
723 /// \remarks The string overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
727 const AkOSChar* in_pszFileName, ///< Application-defined string (title only, or full path, or code...)
730 IAkStdStream *& out_pStream, ///< Returned interface to a standard stream. If the function does not return AK_Success, this pointer is left untouched.
731 bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
743 IAkStdStream *& out_pStream, ///< Returned interface to a standard stream. If the function does not return AK_Success, this pointer is left untouched.
744 bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
753 /// \remarks The string overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
757 const AkOSChar* in_pszFileName, ///< Application-defined string (title only, or full path, or code...)
760 AkAutoStmBufSettings * in_pBufferSettings, ///< Stream buffer settings (it is recommended to pass NULL in order to use the default settings)
761 IAkAutoStream *& out_pStream, ///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched.
762 bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
775 AkAutoStmBufSettings * in_pBufferSettings, ///< Stream buffer settings (it is recommended to pass NULL to use the default settings)
776 IAkAutoStream *& out_pStream, ///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched.
777 bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
784 /// return the memory space in a similar fashion, but without the need to perform any actual file operations.
787 /// consider using the initial implementation from `\\SDK\\source\\StreamManager\\Common\\AkStreamMgr.cpp`.
797 IAkAutoStream *& out_pStream ///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched.
800 /// Start streaming the first "in_pFSFlags->uNumBytesPrefetch" bytes of the file with id "in_fileID" into cache. The stream will be scheduled only after
801 /// all regular streams (not file caching streams) are serviced. The file will stay cached until either the UnpinFileInCache is called,
802 /// or the limit as set by uMaxCachePinnedBytes is reached and another higher priority file (in_uPriority) needs the space.
803 /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API.
804 /// 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.
814 AkPriority in_uPriority ///< Stream caching priority. Note: Caching requests only get serviced after all regular streaming requests.
817 /// 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.
818 /// 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
820 /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API.
821 /// Using UnpinFileInCache() directly does not allow users to take advantage of sound bank data. The file must be explicitly specified.
831 /// 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
833 /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API.
834 /// Using UpdateCachingPriority() directly does not allow users to take advantage of sound bank data. The file must be explicitly specified.
846 /// Retrieves the percentage of the requested buffer size that has been streamed in and stored into stream cache, and whether
851 bool& out_bCacheFull ///< Set to true if the rest of the buffer can not fit into the cache-pinned memory limit.
856 IAkAutoStream * in_pStream, ///< The stream to relocate. Must be a stream created with the memory overload of CreateAutoStm.
bool bIsOpen
True when the file is open (implementations may defer file opening)
Definition: IAkStreamMgr.h:119
AkUInt32 uCachePinnedBytes
Number of bytes that can be pinned into cache.
Definition: IAkStreamMgr.h:180
AkUInt32 uLoopStart
Set to the start of loop (byte offset from the beginning of the stream) for streams that loop,...
Definition: IAkStreamMgr.h:126
AkUInt32 uBufferedSize
Size of available data (specific to IAkAutoStream)
Definition: IAkStreamMgr.h:206
virtual void * GetData(AkUInt32 &out_uSize)=0
AkUInt32 uDirectoryHash
If the implementation uses a hashed directory structure, this is the hash value that should be employ...
Definition: IAkStreamMgr.h:107
virtual IAkStreamMgrProfile * GetStreamMgrProfile()=0
#define AK_MONITOR_DEVICENAME_MAXLENGTH
Definition: IAkStreamMgr.h:42
virtual bool IsNew()=0
virtual AKRESULT SetMinimalBufferSize(AkUInt32 in_uMinBufferSize)=0
virtual AkUInt64 GetPosition(bool *out_pbEndOfStream)=0
virtual void * GetFileDescriptor()=0
virtual IAkDeviceProfile * GetDeviceProfile(AkUInt32 in_uDeviceIndex)=0
AkUInt32 uVirtualBufferingSize
Size of available data including requested data (specific to IAkAutoStream)
Definition: IAkStreamMgr.h:205
virtual AKRESULT ReleaseBuffer()=0
AkUInt32 uLoopEnd
Set to the end of loop (byte offset from the beginning of the stream) for streams that loop,...
Definition: IAkStreamMgr.h:127
Definition: IAkStreamMgr.h:687
virtual ~IAkStreamMgr()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:690
@ AK_OpenModeWriteOvrwr
Write-only access (deletes the file if it already exists)
Definition: IAkStreamMgr.h:75
virtual void GetInfo(AkStreamInfo &out_info)=0
virtual AkUInt32 GetBlockSize()=0
virtual AKRESULT SetPosition(AkInt64 in_iMoveOffset, AkMoveMethod in_eMoveMethod, AkInt64 *out_piRealOffset)=0
virtual AkUInt32 GetNumStreams()=0
AkUInt32 uNumBytesTransferedLowLevel
Transfered amount (from low-level IO only) since last query (Accumulate/Reset)
Definition: IAkStreamMgr.h:208
virtual void GetStreamData(AkStreamData &out_streamData)=0
AkUInt32 uBlockSize
Hard user constraint: When non-zero, buffer size will be a multiple of that number,...
Definition: IAkStreamMgr.h:143
virtual AKRESULT Stop()=0
AkUInt32 uLowLevelBytesTransferred
Number of bytes transferred exclusively via low-level.
Definition: IAkStreamMgr.h:174
virtual void OnProfileEnd()=0
Notify device when monitor sampling ends.
virtual AKRESULT SetMinTargetBufferSize(AkUInt32 in_uMinTargetBufferSize)=0
virtual AkUInt32 GetNominalBuffering()=0
virtual AkUInt32 GetBlockSize()=0
virtual AkStmStatus GetStatus()=0
virtual AKRESULT Read(void *in_pBuffer, AkUInt32 in_uReqSize, bool in_bWait, AkPriority in_priority, AkReal32 in_fDeadline, AkUInt32 &out_uSize)=0
virtual AKRESULT CreateAuto(AkFileID in_fileID, AkFileSystemFlags *in_pFSFlags, const AkAutoStmHeuristics &in_heuristics, AkAutoStmBufSettings *in_pBufferSettings, IAkAutoStream *&out_pStream, bool in_bSyncOpen)=0
virtual void OnProfileStart()=0
Notify device when monitor sampling starts.
AkUInt32 uCompanyID
Company ID (Wwise uses AKCOMPANYID_AUDIOKINETIC, defined in AkTypes.h, for soundbanks and standard st...
Definition: IAkStreamMgr.h:95
AkUInt32 uStringSize
Device name string's size (number of characters)
Definition: IAkStreamMgr.h:158
virtual AKRESULT SetStreamName(const AkOSChar *in_pszStreamName)=0
virtual void GetData(AkDeviceData &out_deviceData)=0
virtual void ClearNew()=0
virtual ~IAkStreamMgrProfile()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:327
virtual void StopMonitoring()=0
virtual AKRESULT SetHeuristics(const AkAutoStmHeuristics &in_heuristics)=0
AkUInt32 uTargetBufferingSize
Total stream buffer size (specific to IAkAutoStream)
Definition: IAkStreamMgr.h:204
Definition: IAkStreamMgr.h:115
virtual AKRESULT SetPosition(AkInt64 in_iMoveOffset, AkMoveMethod in_eMoveMethod, AkInt64 *out_piRealOffset)=0
virtual AKRESULT SetStreamName(const AkOSChar *in_pszStreamName)=0
virtual AkStmStatus WaitForPendingOperation()=0
AkUInt32 uNumLowLevelRequestsCancelled
Number of low-level transfers that were cancelled in the previous monitoring frame.
Definition: IAkStreamMgr.h:177
bool bIsLanguageSpecific
True when the file location depends on language.
Definition: IAkStreamMgr.h:99
virtual AKRESULT CreateAuto(void *in_pBuffer, AkUInt64 in_uSize, const AkAutoStmHeuristics &in_heuristics, IAkAutoStream *&out_pStream)=0
virtual AKRESULT CreateAuto(const AkOSChar *in_pszFileName, AkFileSystemFlags *in_pFSFlags, const AkAutoStmHeuristics &in_heuristics, AkAutoStmBufSettings *in_pBufferSettings, IAkAutoStream *&out_pStream, bool in_bSyncOpen)=0
bool bActive
True if this stream has been active (that is, was ready for I/O or had at least one pending I/O trans...
Definition: IAkStreamMgr.h:211
virtual void Destroy()=0
@ AK_StmStatusPending
Operation pending / The stream is waiting for I/O.
Definition: IAkStreamMgr.h:54
virtual ~IAkDeviceProfile()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:269
virtual AKRESULT RelocateMemoryStream(IAkAutoStream *in_pStream, AkUInt8 *in_pNewStart)=0
Make a memory stream point to a new area in memory, otherwise keeping the exact same state.
virtual AKRESULT StartMonitoring()=0
AkUInt32 uNumActiveStreams
Number of streams that have been active in the previous frame.
Definition: IAkStreamMgr.h:172
virtual AKRESULT QueryBufferingStatus(AkUInt32 &out_uNumBytesAvailable)=0
const AkOSChar * pszName
User-defined stream name (specified through AK::IAkStdStream::SetStreamName() or AK::IAkAutoStream::S...
Definition: IAkStreamMgr.h:117
virtual ~IAkStdStream()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:370
AkUInt32 uTotalBytesTransferred
Number of bytes transferred, including cached transfers.
Definition: IAkStreamMgr.h:173
virtual void GetInfo(AkStreamInfo &out_info)=0
virtual AKRESULT PinFileInCache(AkFileID in_fileID, AkFileSystemFlags *in_pFSFlags, AkPriority in_uPriority)=0
AkUInt32 uUnreferencedCachedBytes
IO memory that is cached but is not currently used for active streams.
Definition: IAkStreamMgr.h:170
virtual AKRESULT CreateStd(const AkOSChar *in_pszFileName, AkFileSystemFlags *in_pFSFlags, AkOpenMode in_eOpenMode, IAkStdStream *&out_pStream, bool in_bSyncOpen)=0
AkFileSystemFlags(AkUInt32 in_uCompanyID, AkUInt32 in_uCodecID, AkUInt32 in_uCustomParamSize, void *in_pCustomParam, bool in_bIsLanguageSpecific, AkFileID in_uCacheID)
Definition: IAkStreamMgr.h:85
virtual void Destroy()=0
virtual IAkStreamProfile * GetStreamProfile(AkUInt32 in_uStreamIndex)=0
Definition: IAkStreamMgr.h:266
virtual AKRESULT GetBuffer(void *&out_pBuffer, AkUInt32 &out_uSize, bool in_bWait)=0
virtual void GetHeuristics(AkAutoStmHeuristics &out_heuristics)=0
Definition: IAkStreamMgr.h:228
virtual AKRESULT CreateStd(AkFileID in_fileID, AkFileSystemFlags *in_pFSFlags, AkOpenMode in_eOpenMode, IAkStdStream *&out_pStream, bool in_bSyncOpen)=0
AkUInt32 uNumLowLevelRequestsPending
Number of low-level transfers that are currently pending.
Definition: IAkStreamMgr.h:178
@ AK_OpenModeWrite
Write-only access (opens the file if it already exists)
Definition: IAkStreamMgr.h:74
@ AK_StmStatusCompleted
Operation completed / Automatic stream reached end.
Definition: IAkStreamMgr.h:53
AkUInt32 uNumBytesTransfered
Transfered amount since last query (Accumulate/Reset)
Definition: IAkStreamMgr.h:207
virtual void GetDesc(AkDeviceDesc &out_deviceDesc)=0
Definition: IAkStreamMgr.h:507
AkUInt32 uNumLowLevelRequestsCompleted
Number of low-level transfers that have completed in the previous monitoring frame.
Definition: IAkStreamMgr.h:176
virtual ~IAkAutoStream()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:510
virtual AKRESULT Start()=0
AkReal32 fAvgCacheEfficiency
Total bytes from cache as a percentage of total bytes.
Definition: IAkStreamMgr.h:175
virtual ~IAkStreamProfile()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:231
virtual void Destroy()=0
AkUInt32 uStringSize
Stream name string's size (number of characters)
Definition: IAkStreamMgr.h:189
virtual AkUInt32 GetNumDevices()=0
AkPriority priority
The stream priority. it should be between AK_MIN_PRIORITY and AK_MAX_PRIORITY (included).
Definition: IAkStreamMgr.h:132
Definition: IAkStreamMgr.h:367
virtual void Cancel()=0
AkUInt32 uMemoryReferenced
Amount of streaming memory referenced by this stream.
Definition: IAkStreamMgr.h:209
virtual AKRESULT Write(void *in_pBuffer, AkUInt32 in_uReqSize, bool in_bWait, AkPriority in_priority, AkReal32 in_fDeadline, AkUInt32 &out_uSize)=0
virtual AKRESULT UnpinFileInCache(AkFileID in_fileID, AkPriority in_uPriority)=0
virtual void GetStreamRecord(AkStreamRecord &out_streamRecord)=0
#define AK_MONITOR_STREAMNAME_MAXLENGTH
Definition: IAkStreamMgr.h:41
virtual bool IsNew()=0
virtual AKRESULT GetBufferStatusForPinnedFile(AkFileID in_fileID, AkReal32 &out_fPercentBuffered, bool &out_bCacheFull)=0
virtual AKRESULT UpdateCachingPriority(AkFileID in_fileID, AkPriority in_uPriority, AkPriority in_uOldPriority)=0
virtual void * GetFileDescriptor()=0
virtual AkUInt64 GetPosition(bool *out_pbEndOfStream)=0
virtual void ClearNew()=0
Definition: IAkStreamMgr.h:324
Was this page helpful?
Need Support?
Questions? Problems? Need more info? Contact us, and we can help!
Visit our Support pageTell us about your project. We're here to help.
Register your project and we'll help you get started with no strings attached!
Get started with Wwise