Wwise SDK 2018.1.11
_i_ak_stream_mgr_8h_source
Version
menu_open
link
Wwise SDK 2018.1.11
|
IAkStreamMgr.h
Go to the documentation of this file.
86 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.
116 const AkOSChar * pszName; ///< User-defined stream name (specified through AK::IAkStdStream::SetStreamName() or AK::IAkAutoStream::SetStreamName())
125 AkUInt32 uLoopStart; ///< Set to the start of loop (byte offset from the beginning of the stream) for streams that loop, 0 otherwise
126 AkUInt32 uLoopEnd; ///< Set to the end of loop (byte offset from the beginning of the stream) for streams that loop, 0 otherwise
127 AkUInt8 uMinNumBuffers; ///< Minimum number of buffers if you plan to own more than one buffer at a time, 0 or 1 otherwise
128 ///< \remarks You should always release buffers as fast as possible, therefore this heuristic should be used only when
129 ///< dealing with special contraints, like drivers or hardware that require more than one buffer at a time.\n
130 ///< Also, this is only a heuristic: it does not guarantee that data will be ready when calling AK::IAkAutoStream::GetBuffer().
131 AkPriority priority; ///< The stream priority. it should be between AK_MIN_PRIORITY and AK_MAX_PRIORITY (included).
137 AkUInt32 uBufferSize; ///< Hard user constraint: When non-zero, forces the I/O buffer to be of size uBufferSize
140 AkUInt32 uMinBufferSize; ///< Soft user constraint: When non-zero, specifies a minimum buffer size
142 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.
167 AkUInt32 uUnreferencedCachedBytes; ///< IO memory that is cached but is not currently used for active streams.
173 AkUInt32 uNumLowLevelRequestsCompleted; ///< Number of low-level transfers that have completed in the previous monitoring frame
174 AkUInt32 uNumLowLevelRequestsCancelled; ///< Number of low-level transfers that were cancelled in the previous monitoring frame
175 AkUInt32 uNumLowLevelRequestsPending; ///< Number of low-level transfers that are currently pending
202 AkUInt32 uVirtualBufferingSize; ///< Size of available data including requested data (specific to IAkAutoStream)
205 AkUInt32 uNumBytesTransferedLowLevel;///< Transfered amount (from low-level IO only) since last query (Accumulate/Reset)
208 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
301 /// \remarks GetStreamProfile() refers to streams by index, which must honor the call to AK::IAkDeviceProfile::GetNumStreams().
336 /// \remarks GetDeviceProfile() refers to devices by index, which must honor the call to AK::IAkStreamMgrProfile::GetNumDevices().
374 /// The default implementation of the Stream Manager returns its file descriptor (see AkStreamMgrModule.h).
385 /// \remark Queries the low-level I/O, by calling AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize() with the
397 /// \warning Use only with a multiple of the block size, queried via AK::IAkStdStream::GetBlockSize().
398 /// \remarks If the call is asynchronous (in_bWait = false), wait until AK::IAkStdStream::GetStatus() stops returning AK_StmStatusPending.
399 /// \return AK_Success if the operation was successfully scheduled (but not necessarily completed)
412 /// \warning Use only with a multiple of the block size, queried via AK::IAkStdStream::GetBlockSize().
413 /// \remarks If the call is asynchronous (in_bWait = false), wait until GetStatus() stops returning AK_StmStatusPending.
427 /// \remarks If an operation is pending, there is no guarantee that the position was queried before (or after) the operation was completed.
432 bool * out_pbEndOfStream ///< Returned end-of-stream flag, only for streams opened with AK_OpenModeRead (can pass NULL)
443 AkMoveMethod in_eMoveMethod, ///< Seek method, from the beginning, end, or current file position
444 AkInt64 * out_piRealOffset ///< The actual seek offset may differ from the expected value when the block size is bigger than 1.
450 /// \remarks This method can block the caller for the whole duration of the I/O operation, if the request was already posted.
505 /// The default implementation of the Stream Manager returns its file descriptor (see AkStreamMgrModule.h).
534 /// 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.
535 /// The system will predict the minimum size to buffer and will consider this value as the minimal size to be the target.
541 AkUInt32 in_uMinTargetBufferSize ///< Minimum size to buffer ahead in an automated stream. (in bytes)
552 /// \remark Queries the actual low-level I/O device, by calling AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize() with the
560 /// The buffering is defined as the number of bytes that the stream has buffered, excluding the number
562 /// \remark The returned value corresponds to the buffering status at that moment, and does not even
567 /// - AK_NoMoreData: Some or no data is available, but the end of file has been reached. The stream will not buffer any more data.
597 /// already streamed into the Stream Manager's memory. The stream position is updated when buffers
600 /// If the user does not own a buffer, it returns the position of the beginning of the buffer that
609 /// The next call to AK::IAkAutoStream::GetBuffer() will grant data that corresponds to the position specified here.
618 AkInt64 * out_piRealOffset ///< The actual seek offset may differ from the expected value when the low-level's block size is greater than 1.
629 /// \remarks Grants a buffer if data is available. Each successful call to this method returns a new
631 /// Buffers should be released as soon as they are not needed, using AK::IAkAutoStream::ReleaseBuffer().
632 /// \aknote AK::IAkAutoStream::ReleaseBuffer() does not take any argument, because it releases buffers in order. \endaknote
635 /// - AK_NoDataReady : the buffer is not granted yet (never happens when called with in_bWait flag)
636 /// - AK_NoMoreData : the buffer was granted but reached end of file (next call will return with size 0)
647 /// \return AK_Success if a valid buffer was released, AK_Fail if the user did not own any buffer.
648 /// \note To implementers: Clients like the sound engine may release buffers until this function returns AK_Fail.
698 /// \remarks The string overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
702 const AkOSChar* in_pszFileName, ///< Application-defined string (title only, or full path, or code...)
705 IAkStdStream *& out_pStream, ///< Returned interface to a standard stream. If the function does not return AK_Success, this pointer is left untouched.
706 bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
718 IAkStdStream *& out_pStream, ///< Returned interface to a standard stream. If the function does not return AK_Success, this pointer is left untouched.
719 bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
728 /// \remarks The string overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
732 const AkOSChar* in_pszFileName, ///< Application-defined string (title only, or full path, or code...)
735 AkAutoStmBufSettings * in_pBufferSettings, ///< Stream buffer settings (it is recommended to pass NULL in order to use the default settings)
736 IAkAutoStream *& out_pStream, ///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched.
737 bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
750 AkAutoStmBufSettings * in_pBufferSettings, ///< Stream buffer settings (it is recommended to pass NULL to use the default settings)
751 IAkAutoStream *& out_pStream, ///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched.
752 bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
755 /// Start streaming the first "in_pFSFlags->uNumBytesPrefetch" bytes of the file with id "in_fileID" into cache. The stream will be scheduled only after
756 /// all regular streams (not file caching streams) are serviced. The file will stay cached until either the UnpinFileInCache is called,
757 /// or the limit as set by uMaxCachePinnedBytes is reached and another higher priority file (in_uPriority) needs the space.
758 /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API.
759 /// 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.
769 AkPriority in_uPriority ///< Stream caching priority. Note: Caching requests only get serviced after all regular streaming requests.
772 /// 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.
773 /// 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
775 /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API.
776 /// Using UnpinFileInCache() directly does not allow users to take advantage of sound bank data. The file must be explicitly specified.
786 /// 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
788 /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API.
789 /// Using UpdateCachingPriority() directly does not allow users to take advantage of sound bank data. The file must be explicitly specified.
801 /// Retrieves the percentage of the requested buffer size that has been streamed in and stored into stream cache, and whether
806 bool& out_bCacheFull ///< Set to true if the rest of the buffer can not fit into the cache-pinned memory limit.
virtual void OnProfileEnd()=0
Notify device when monitor sampling ends.
virtual void Destroy()=0
virtual void Destroy()=0
virtual AKRESULT Stop()=0
virtual ~IAkStreamMgrProfile()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:315
AkPriority priority
The stream priority. it should be between AK_MIN_PRIORITY and AK_MAX_PRIORITY (included).
Definition: IAkStreamMgr.h:131
AkUInt32 uTotalBytesTransferred
Number of bytes transferred, including cached transfers.
Definition: IAkStreamMgr.h:170
virtual AkUInt32 GetNumDevices()=0
Operation pending / The stream is waiting for I/O.
Definition: IAkStreamMgr.h:55
virtual ~IAkStdStream()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:356
AkUInt32 uLowLevelBytesTransferred
Number of bytes transferred exclusively via low-level.
Definition: IAkStreamMgr.h:171
AkReal32 fAvgCacheEfficiency
Total bytes from cache as a percentage of total bytes.
Definition: IAkStreamMgr.h:172
virtual bool IsNew()=0
AkUInt32 uUnreferencedCachedBytes
IO memory that is cached but is not currently used for active streams.
Definition: IAkStreamMgr.h:167
Write-only access (opens the file if it already exists)
Definition: IAkStreamMgr.h:75
virtual void Destroy()=0
virtual void ClearNew()=0
virtual AKRESULT Write(void *in_pBuffer, AkUInt32 in_uReqSize, bool in_bWait, AkPriority in_priority, AkReal32 in_fDeadline, AkUInt32 &out_uSize)=0
AkUInt32 uNumLowLevelRequestsCompleted
Number of low-level transfers that have completed in the previous monitoring frame.
Definition: IAkStreamMgr.h:173
virtual AKRESULT GetBufferStatusForPinnedFile(AkFileID in_fileID, AkReal32 &out_fPercentBuffered, bool &out_bCacheFull)=0
AkUInt32 uLoopStart
Set to the start of loop (byte offset from the beginning of the stream) for streams that loop,...
Definition: IAkStreamMgr.h:125
virtual AKRESULT QueryBufferingStatus(AkUInt32 &out_uNumBytesAvailable)=0
virtual ~IAkAutoStream()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:487
AkUInt32 uNumLowLevelRequestsPending
Number of low-level transfers that are currently pending.
Definition: IAkStreamMgr.h:175
AkUInt32 uNumLowLevelRequestsCancelled
Number of low-level transfers that were cancelled in the previous monitoring frame.
Definition: IAkStreamMgr.h:174
virtual AKRESULT SetPosition(AkInt64 in_iMoveOffset, AkMoveMethod in_eMoveMethod, AkInt64 *out_piRealOffset)=0
virtual AkUInt32 GetNominalBuffering()=0
AkUInt32 uStringSize
Device name string's size (number of characters)
Definition: IAkStreamMgr.h:155
Definition: IAkStreamMgr.h:352
virtual AkUInt32 GetNumStreams()=0
virtual ~IAkDeviceProfile()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:259
AkUInt32 uNumBytesTransfered
Transfered amount since last query (Accumulate/Reset)
Definition: IAkStreamMgr.h:204
Operation completed / Automatic stream reached end.
Definition: IAkStreamMgr.h:54
virtual void StopMonitoring()=0
Definition: IAkStreamMgr.h:311
bool bIsLanguageSpecific
True when the file location depends on language.
Definition: IAkStreamMgr.h:99
Definition: IAkStreamMgr.h:483
virtual AKRESULT UpdateCachingPriority(AkFileID in_fileID, AkPriority in_uPriority, AkPriority in_uOldPriority)=0
virtual AKRESULT UnpinFileInCache(AkFileID in_fileID, AkPriority in_uPriority)=0
virtual AkUInt64 GetPosition(bool *out_pbEndOfStream)=0
virtual void GetStreamRecord(AkStreamRecord &out_streamRecord)=0
virtual void GetData(AkDeviceData &out_deviceData)=0
bool bIsOpen
True when the file is open (implementations may defer file opening)
Definition: IAkStreamMgr.h:118
Definition: IAkStreamMgr.h:113
virtual AKRESULT SetStreamName(const AkOSChar *in_pszStreamName)=0
virtual void * GetData(AkUInt32 &out_uSize)=0
virtual void * GetFileDescriptor()=0
virtual IAkStreamMgrProfile * GetStreamMgrProfile()=0
virtual AkUInt32 GetBlockSize()=0
virtual AKRESULT SetHeuristics(const AkAutoStmHeuristics &in_heuristics)=0
virtual void GetInfo(AkStreamInfo &out_info)=0
Write-only access (deletes the file if it already exists)
Definition: IAkStreamMgr.h:76
Definition: IAkStreamMgr.h:219
virtual ~IAkStreamProfile()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:223
virtual void Cancel()=0
virtual AKRESULT SetMinimalBufferSize(AkUInt32 in_uMinBufferSize)=0
virtual void GetInfo(AkStreamInfo &out_info)=0
virtual void * GetFileDescriptor()=0
virtual AKRESULT GetBuffer(void *&out_pBuffer, AkUInt32 &out_uSize, bool in_bWait)=0
AkUInt32 uNumBytesTransferedLowLevel
Transfered amount (from low-level IO only) since last query (Accumulate/Reset)
Definition: IAkStreamMgr.h:205
virtual IAkDeviceProfile * GetDeviceProfile(AkUInt32 in_uDeviceIndex)=0
#define AK_MONITOR_STREAMNAME_MAXLENGTH
Definition: IAkStreamMgr.h:42
AkUInt32 uMemoryReferenced
Amount of streaming memory referenced by this stream.
Definition: IAkStreamMgr.h:206
AkUInt32 uVirtualBufferingSize
Size of available data including requested data (specific to IAkAutoStream)
Definition: IAkStreamMgr.h:202
#define AK_MONITOR_DEVICENAME_MAXLENGTH
Definition: IAkStreamMgr.h:43
virtual AKRESULT CreateAuto(const AkOSChar *in_pszFileName, AkFileSystemFlags *in_pFSFlags, const AkAutoStmHeuristics &in_heuristics, AkAutoStmBufSettings *in_pBufferSettings, IAkAutoStream *&out_pStream, bool in_bSyncOpen)=0
virtual AkUInt64 GetPosition(bool *out_pbEndOfStream)=0
AkUInt32 uCompanyID
Company ID (Wwise uses AKCOMPANYID_AUDIOKINETIC, defined in AkTypes.h, for soundbanks and standard st...
Definition: IAkStreamMgr.h:95
virtual void GetDesc(AkDeviceDesc &out_deviceDesc)=0
virtual AkUInt32 GetBlockSize()=0
virtual ~IAkStreamMgr()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:665
virtual IAkStreamProfile * GetStreamProfile(AkUInt32 in_uStreamIndex)=0
Definition: IAkStreamMgr.h:661
AkFileSystemFlags(AkUInt32 in_uCompanyID, AkUInt32 in_uCodecID, AkUInt32 in_uCustomParamSize, void *in_pCustomParam, bool in_bIsLanguageSpecific, AkFileID in_uCacheID)
Definition: IAkStreamMgr.h:86
Definition: IAkStreamMgr.h:255
virtual AKRESULT PinFileInCache(AkFileID in_fileID, AkFileSystemFlags *in_pFSFlags, AkPriority in_uPriority)=0
virtual bool IsNew()=0
AkUInt32 uStringSize
Stream name string's size (number of characters)
Definition: IAkStreamMgr.h:186
virtual AKRESULT ReleaseBuffer()=0
virtual AKRESULT CreateStd(const AkOSChar *in_pszFileName, AkFileSystemFlags *in_pFSFlags, AkOpenMode in_eOpenMode, IAkStdStream *&out_pStream, bool in_bSyncOpen)=0
virtual AkStmStatus GetStatus()=0
virtual void GetHeuristics(AkAutoStmHeuristics &out_heuristics)=0
AkUInt32 uCachePinnedBytes
Number of bytes that can be pinned into cache.
Definition: IAkStreamMgr.h:177
virtual AKRESULT SetPosition(AkInt64 in_iMoveOffset, AkMoveMethod in_eMoveMethod, AkInt64 *out_piRealOffset)=0
const AkOSChar * pszName
User-defined stream name (specified through AK::IAkStdStream::SetStreamName() or AK::IAkAutoStream::S...
Definition: IAkStreamMgr.h:116
AkUInt32 uBlockSize
Hard user constraint: When non-zero, buffer size will be a multiple of that number,...
Definition: IAkStreamMgr.h:142
virtual AKRESULT Read(void *in_pBuffer, AkUInt32 in_uReqSize, bool in_bWait, AkPriority in_priority, AkReal32 in_fDeadline, AkUInt32 &out_uSize)=0
virtual void ClearNew()=0
virtual void OnProfileStart()=0
Notify device when monitor sampling starts.
virtual AKRESULT Start()=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:208
AkUInt32 uLoopEnd
Set to the end of loop (byte offset from the beginning of the stream) for streams that loop,...
Definition: IAkStreamMgr.h:126
AkUInt32 uTargetBufferingSize
Total stream buffer size (specific to IAkAutoStream)
Definition: IAkStreamMgr.h:201
virtual AKRESULT SetMinTargetBufferSize(AkUInt32 in_uMinTargetBufferSize)=0
virtual AKRESULT StartMonitoring()=0
AkUInt32 uBufferedSize
Size of available data (specific to IAkAutoStream)
Definition: IAkStreamMgr.h:203
virtual AKRESULT SetStreamName(const AkOSChar *in_pszStreamName)=0
virtual void GetStreamData(AkStreamData &out_streamData)=0
AkUInt32 uNumActiveStreams
Number of streams that have been active in the previous frame.
Definition: IAkStreamMgr.h:169
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