Wwise SDK 2019.1.11
_ak_stream_mgr_module_8h_source
Version
menu_open
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()
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