Wwise SDK 2019.1.11
_ak_stream_mgr_module_8h_source
版本
menu_open
警告:系统已根据您所用大版本 (2019.1.11.7296) 自动跳转至最新文档。若想访问特定版本的文档,请从 Audiokinetic Launcher 下载离线文档,并在 Wwise 设计程序中勾选 Offline Documentation 选项。
link
Wwise SDK 2019.1.11
|
AkStreamMgrModule.h
31 /// Contains the default Stream Manager's implementation-specific interfaces that altogether constitute
32 /// the Low-Level I/O submodule. This submodule needs to be implemented by the game. All I/O requests
71 void * pIOMemory; ///< Pointer for I/O memory allocated by user. This is fed directly to AK::MemoryMgr::CreatePool().
74 AkUInt32 uIOMemorySize; ///< Size of memory pool for I/O (for automatic streams). It is passed directly to AK::MemoryMgr::CreatePool(), after having been rounded down to a multiple of uGranularity.
75 AkUInt32 uIOMemoryAlignment; ///< I/O memory pool alignment. It is passed directly to AK::MemoryMgr::CreatePool().
76 AkMemPoolAttributes ePoolAttributes; ///< Attributes for internal I/O memory pool. Note that these pools are always allocated internally as AkFixedSizeBlocksMode-style pools. Here, specify the block allocation type (AkMalloc, and so on). It is passed directly to AK::MemoryMgr::CreatePool().
80 AkReal32 fTargetAutoStmBufferLength; ///< Targetted automatic stream buffer length (ms). When a stream reaches that buffering, it stops being scheduled for I/O except if the scheduler is idle.
81 AkUInt32 uMaxConcurrentIO; ///< Maximum number of transfers that can be sent simultaneously to the Low-Level I/O (applies to AK_SCHEDULER_DEFERRED_LINED_UP device only).
82 bool bUseStreamCache; ///< If true the device attempts to reuse IO buffers that have already been streamed from disk. This is particularly useful when streaming small looping sounds. The drawback is a small CPU hit when allocating memory, and a slightly larger memory footprint in the StreamManager pool.
83 AkUInt32 uMaxCachePinnedBytes; ///< Maximum number of bytes that can be "pinned" using AK::SoundEngine::PinEventInStreamCache() or AK::IAkStreamMgr::PinFileInCache()
88 /// Requests to Low-Level IO are synchronous. The streaming device expects a blocking I/O hook at creation time (IAkIOHookBlocking interface, see CreateDevice()).
91 /// Requests to Low-Level IO are asynchronous, but posted one after the other, starting with streams that need data the most.
92 /// The streaming device expects a deferred I/O hook at creation time (IAkIOHookDeferred interface, see CreateDevice()).
93 /// Up to AkDeviceSettings::uMaxConcurrentIO requests can be sent to the Low-Level I/O at the same time.
109 AkDeviceID deviceID; ///< Device ID, obtained from CreateDevice() \sa AK::IAkStreamMgr::CreateDevice()
113 /// Structure for synchronous transfers handshaking with the Low-Level I/O. Used with blocking I/O hooks.
119 AkUInt32 uRequestedSize; ///< Exact number of requested bytes for this transfer. Always equal to or smaller than uBufferSize.
123 /// Callback function prototype definition used for asynchronous I/O transfers between the Stream Manager
126 /// - If you return AK_Fail, all streams awaiting for this transfer are marked as invalid and will stop. An "IO error" notification is posted to the capture log.
127 /// - If the transfer was cancelled by the Stream Manager while it was in the Low-Level IO, you must return AK_Success, whether
128 /// you performed the operation or not. The Stream Manager knows that it was cancelled, so it will not try to use it after you call it back.
133 AkAsyncIOTransferInfo * in_pTransferInfo, ///< Pointer to the AkAsyncIOTransferInfo structure that was passed to corresponding Read() or Write() call.
134 AKRESULT in_eResult ///< Result of transfer: AK_Success or AK_Fail (streams waiting for this transfer become invalid).
137 /// Structure for asynchronous transfers handshaking with the Low-Level I/O. Extends AkIOTransferInfo.
145 AkIOCallback pCallback; ///< Callback function used to notify the high-level device when the transfer is complete.
146 void * pCookie; ///< Reserved. The I/O device uses this cookie to retrieve the owner of the transfer.
160 AkPriority priority; ///< Operation priority (at the time it was scheduled and sent to the Low-Level I/O). Range is [AK_MIN_PRIORITY,AK_MAX_PRIORITY], inclusively.
169 // Audiokinetic Stream Manager's implementation-specific interfaces of the Low-Level IO submodule.
242 /// Read data from the file described by in_fileDesc, in address out_pBuffer and with size and position
243 /// passed within io_transferInfo. When transfer is complete, return with the proper return code.
247 /// device as "in_fileDesc.uSector * Block_Size + Stream_Position", where Block_Size is obtained
260 /// Write data to the file described by in_fileDesc, from address in_pData and with size and position
261 /// passed within io_transferInfo. When transfer is complete, return with the proper return code.
264 /// device as "in_fileDesc.uSector * Block_Size + Stream_Position", where Block_Size is obtained
280 /// I/O streaming technology. You will receive up to AkDeviceSettings::uMaxConcurrentIO requests
281 /// at the same time. You may queue them into your own system, and even use the heuristics passed
291 /// Cancel() is provided in order to inform you that the streaming device will flush this transfer
303 /// - Queue up your read request with address, size and file position specified in io_transferInfo.
313 /// device as "in_fileDesc.uSector * Block_Size + Stream_Position", where Block_Size is obtained
327 /// - Queue up your write request with address, size and file position specified in io_transferInfo.
329 /// AkAsyncIOTransferInfo::pCallback. However, if you return AK_Fail() from Write(), do not call
337 /// device as "in_fileDesc.uSector * Block_Size + Stream_Position", where Block_Size is obtained
349 /// Notifies that a transfer request is cancelled. It will be flushed by the streaming device when completed.
350 /// Cancellation is normal and happens regularly; for example, whenever a sound stops before the end
351 /// or stops looping. It happens even more frequently when buffering (AkDeviceSettings::fTargetAutoStmBufferLength
352 /// and AkDeviceSettings::uGranularity) is large and when you low-level IO hook accepts many concurrent requests
355 /// - Cancel() simply informs the Low-Level I/O that a specific transfer will be flushed upon reception.
356 /// The Low-Level I/O may use this information to stop this transfer right away, or not (it is internally tagged
357 /// by the high-level device as cancelled). Nevertheless, the callback function MUST be called for cancelled
359 /// - When calling the callback function of a cancelled transfer, pass it *AK_Success*. Passing AK_Fail
360 /// to AkAsyncIOTransfer::pCallback has the effect of killing the stream once and for all. This is not
362 /// - If io_bCancelAllTransfersForThisFile is set, you may cancel all transfers for this file at once.
363 /// Leave io_bCancelAllTransfersForThisFile to true if you don't want to be called again. For example, if
364 /// you don't do anything special in Cancel(), leave it to true. This will reduce the amount of useless calls.
365 /// If you set it to false, Cancel() will be called again for each remaining pending transfer that need to be cancelled.
366 /// - If io_bCancelAllTransfersForThisFile is not set, Cancel() is only called for a subset of pending
367 /// transfers for this file. You must not set it to true, as Cancel() needs to be called explicitly for each transfer that should be cancelled.
369 /// - The calling thread holds the stream's lock. You may call the callback function directly from here
370 /// (if you can guarantee that the I/O buffer will not be accessed in the meantime), but you must not wait here
372 /// - Likewise, if you resolve transfers with your own thread and use a lock to protect your transfers queue,
373 /// be careful not to run into a deadlock. Cancel() can be executed by any thread. Thus, if you need to lock your queue
374 /// in Cancel(), you must never hold this lock when calling back transfers, either from within Cancel() or from your
375 /// worker thread's routine. Lock your list, dequeue the transfer if you can, unlock, and call pCallback if and only if
376 /// the transfer was found and dequeued. On the other hand, if you choose not to do anything in Cancel(), the lock only protects
377 /// your list between Read()/Write() and your worker thread's routine, and since the device I/O thread does not hold the
378 /// stream's lock while calling Read()/Write(), your worker thread may therefore hold it while calling back transfers.
379 /// - A race condition exists when cancelling all transfers (io_bCancelAllTransfersForThisFile is true) directly from within this hook.
380 /// If you handle the io_bCancelAllTransfersForThisFile == true case, you need to defer calling the completion callback to later
381 /// (from your usual I/O completion thread, for example). This will be fixed in a future version of Wwise.
385 bool & io_bCancelAllTransfersForThisFile ///< Flag indicating whether all transfers should be cancelled for this file (see notes in function description).
390 /// registered to the Stream Manager (using AK::StreamMgr::SetFileLocationResolver()). Its purpose
398 /// If you wish to create multiple devices, then you should have a separate object that implements
399 /// AK::StreamMgr::IAkFileLocationResolver and registers to the Stream Manager as such. This object
400 /// will be used to dispatch the file open request to the appropriate device. The strategy you will
457 bool & io_bSyncOpen, ///< If true, the file must be opened synchronously. Otherwise it is left at the File Location Resolver's discretion. Return false if Open needs to be deferred.
508 bool & io_bSyncOpen, ///< If true, the file must be opened synchronously. Otherwise it is left at the File Location Resolver's discretion. Return false if Open needs to be deferred.
536 AkStreamMgrSettings & out_settings ///< Returned AkStreamMgrSettings structure with default values.
549 IAkFileLocationResolver * in_pFileLocationResolver ///< Interface to your File Location Resolver
567 /// \return The device ID. AK_INVALID_DEVICE_ID if there was an error and it could not be created.
573 /// statically cast internally into one of these hooks. Implementing the wrong (or no) interface
578 /// - The returned device ID should be kept by the Low-Level IO, to assign it to file descriptors
586 IAkLowLevelIOHook * in_pLowLevelHook ///< Associated low-level I/O hook. Pass either a IAkIOHookBlocking or a IAkIOHookDeferred interface, consistent with the type of the scheduler.
590 /// \warning This function is not thread-safe. No stream should exist for that device when it is destroyed.
608 /// Set the current language once and only once, here. The language name is stored in a static buffer
610 /// AK::StreamMgr::IAkFileLocationResolver implementations query this string. They may use it to
611 /// construct a file path (for e.g. SDK/samples/SoundEngine/Common/AkFileLocationBase.cpp), or to
612 /// find a language-specific file within a look-up table (for e.g. SDK/samples/SoundEngine/Common/AkFilePackageLUT.cpp).
613 /// Pass a valid null-terminated string, without a trailing slash or backslash. Empty strings are accepted.
616 /// \return AK_Success if successful (if language string has less than AK_MAX_LANGUAGE_NAME_SIZE characters). AK_Fail otherwise.
625 /// Get the current language. The language name is stored in a static buffer inside the Stream Manager,
626 /// with AK::StreamMgr::SetCurrentLanguage(). In order to resolve localized (language-specific) file location,
627 /// AK::StreamMgr::IAkFileLocationResolver implementations query this string. They may use it to
628 /// construct a file path (for e.g. SDK/samples/SoundEngine/Common/AkFileLocationBase.cpp), or to
629 /// find a language-specific file within a look-up table (for e.g. SDK/samples/SoundEngine/Common/AkFilePackageLUT.cpp).
void * pCookie
Reserved. The I/O device uses this cookie to retrieve the owner of the transfer.
Definition: AkStreamMgrModule.h:146
virtual ~IAkIOHookDeferred()
Virtual destructor on interface to avoid warnings.
Definition: AkStreamMgrModule.h:297
AkUInt32 uIOMemoryAlignment
I/O memory pool alignment. It is passed directly to AK::MemoryMgr::CreatePool().
Definition: AkStreamMgrModule.h:75
Base interface for Low-Level I/O hooks. Defines common methods across both types of hooks.
Definition: AkStreamMgrModule.h:174
Definition: AkStreamMgrModule.h:143
Definition: AkPlatformFuncs.h:49
Definition: AkStreamMgrModule.h:100
AKSOUNDENGINE_API AKRESULT DestroyDevice(AkDeviceID in_deviceID)
AKSOUNDENGINE_API AKRESULT SetCurrentLanguage(const AkOSChar *in_pszLanguageName)
virtual AKRESULT Open(const AkOSChar *in_pszFileName, AkOpenMode in_eOpenMode, AkFileSystemFlags *in_pFlags, bool &io_bSyncOpen, AkFileDesc &io_fileDesc)=0
virtual AkUInt32 GetDeviceData()=0
void(* AkLanguageChangeHandler)(const AkOSChar *const in_pLanguageName, void *in_pCookie)
Definition: AkStreamMgrModule.h:641
AkUInt32 uMaxCachePinnedBytes
Maximum number of bytes that can be "pinned" using AK::SoundEngine::PinEventInStreamCache() or AK::IA...
Definition: AkStreamMgrModule.h:83
AkUInt32 uRequestedSize
Exact number of requested bytes for this transfer. Always equal to or smaller than uBufferSize.
Definition: AkStreamMgrModule.h:119
Definition: IAkStreamMgr.h:662
AKSOUNDENGINE_API AkMemPoolId GetPoolID()
AkUInt32 uMaxConcurrentIO
Maximum number of transfers that can be sent simultaneously to the Low-Level I/O (applies to AK_SCHED...
Definition: AkStreamMgrModule.h:81
AkReal32 fTargetAutoStmBufferLength
Targetted automatic stream buffer length (ms). When a stream reaches that buffering,...
Definition: AkStreamMgrModule.h:80
bool bUseStreamCache
If true the device attempts to reuse IO buffers that have already been streamed from disk....
Definition: AkStreamMgrModule.h:82
AKSOUNDENGINE_API void GetDefaultSettings(AkStreamMgrSettings &out_settings)
virtual ~IAkLowLevelIOHook()
Virtual destructor on interface to avoid warnings.
Definition: AkStreamMgrModule.h:177
virtual AKRESULT Open(AkFileID in_fileID, AkOpenMode in_eOpenMode, AkFileSystemFlags *in_pFlags, bool &io_bSyncOpen, AkFileDesc &io_fileDesc)=0
AkPriority priority
Operation priority (at the time it was scheduled and sent to the Low-Level I/O). Range is [AK_MIN_PRI...
Definition: AkStreamMgrModule.h:160
Definition: AkStreamMgrModule.h:70
AkUInt32 uBufferSize
Size of the buffer in which the I/O hook can write to.
Definition: AkStreamMgrModule.h:118
virtual void Cancel(AkFileDesc &in_fileDesc, AkAsyncIOTransferInfo &io_transferInfo, bool &io_bCancelAllTransfersForThisFile)=0
AKSOUNDENGINE_API AkDeviceID CreateDevice(const AkDeviceSettings &in_settings, IAkLowLevelIOHook *in_pLowLevelHook)
AkUInt32 uGranularity
I/O requests granularity (typical bytes/request).
Definition: AkStreamMgrModule.h:77
Definition: AkStreamMgrModule.h:158
virtual void GetDeviceDesc(AkDeviceDesc &out_deviceDesc)=0
CAkFilePackage * pPackage
If this file is in a File Package, this will be the
Definition: AkStreamMgrModule.h:110
virtual AkUInt32 GetBlockSize(AkFileDesc &in_fileDesc)=0
Definition: AkStreamMgrModule.h:116
virtual AKRESULT Close(AkFileDesc &in_fileDesc)=0
AkIOCallback pCallback
Callback function used to notify the high-level device when the transfer is complete.
Definition: AkStreamMgrModule.h:145
virtual AKRESULT Read(AkFileDesc &in_fileDesc, const AkIoHeuristics &in_heuristics, AkAsyncIOTransferInfo &io_transferInfo)=0
AKSOUNDENGINE_API IAkFileLocationResolver * GetFileLocationResolver()
AKSOUNDENGINE_API IAkStreamMgr * Create(const AkStreamMgrSettings &in_settings)
AKSOUNDENGINE_API void FlushAllCaches()
virtual AKRESULT Write(AkFileDesc &in_fileDesc, const AkIoHeuristics &in_heuristics, void *in_pData, AkIOTransferInfo &io_transferInfo)=0
AKSOUNDENGINE_API void GetDefaultDeviceSettings(AkDeviceSettings &out_settings)
virtual AKRESULT Read(AkFileDesc &in_fileDesc, const AkIoHeuristics &in_heuristics, void *out_pBuffer, AkIOTransferInfo &in_transferInfo)=0
AKSOUNDENGINE_API void SetFileLocationResolver(IAkFileLocationResolver *in_pFileLocationResolver)
AkMemPoolAttributes ePoolAttributes
Attributes for internal I/O memory pool. Note that these pools are always allocated internally as AkF...
Definition: AkStreamMgrModule.h:76
AKSOUNDENGINE_API void RemoveLanguageChangeObserver(void *in_pCookie)
AKSOUNDENGINE_API AKRESULT AddLanguageChangeObserver(AkLanguageChangeHandler in_handler, void *in_pCookie)
virtual ~IAkFileLocationResolver()
Virtual destructor on interface to avoid warnings.
Definition: AkStreamMgrModule.h:408
virtual ~IAkIOHookBlocking()
Virtual destructor on interface to avoid warnings.
Definition: AkStreamMgrModule.h:237
AkUInt32 uIOMemorySize
Size of memory pool for I/O (for automatic streams). It is passed directly to AK::MemoryMgr::CreatePo...
Definition: AkStreamMgrModule.h:74
Definition: AkStreamMgrModule.h:53
virtual AKRESULT Write(AkFileDesc &in_fileDesc, const AkIoHeuristics &in_heuristics, AkAsyncIOTransferInfo &io_transferInfo)=0
AKSOUNDENGINE_API const AkOSChar * GetCurrentLanguage()