Wwise SDK 2018.1.11
_ak_stream_mgr_module_8h_source
Version
Other Documentation
menu_open
link
Wwise SDK 2018.1.11
|
AkStreamMgrModule.h
Go to the documentation of this file.
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
69 void * pIOMemory; ///< Pointer for I/O memory allocated by user. This is fed directly to AK::MemoryMgr::CreatePool().
72 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.
73 AkUInt32 uIOMemoryAlignment; ///< I/O memory pool alignment. It is passed directly to AK::MemoryMgr::CreatePool().
74 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().
78 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.
79 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).
80 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.
81 AkUInt32 uMaxCachePinnedBytes; ///< Maximum number of bytes that can be "pinned" using AK::SoundEngine::PinEventInStreamCache() or AK::IAkStreamMgr::PinFileInCache()
86 /// Requests to Low-Level IO are synchronous. The streaming device expects a blocking I/O hook at creation time (IAkIOHookBlocking interface, see CreateDevice()).
89 /// Requests to Low-Level IO are asynchronous, but posted one after the other, starting with streams that need data the most.
90 /// The streaming device expects a deferred I/O hook at creation time (IAkIOHookDeferred interface, see CreateDevice()).
91 /// Up to AkDeviceSettings::uMaxConcurrentIO requests can be sent to the Low-Level I/O at the same time.
107 AkDeviceID deviceID; ///< Device ID, obtained from CreateDevice() \sa AK::IAkStreamMgr::CreateDevice()
110 /// Structure for synchronous transfers handshaking with the Low-Level I/O. Used with blocking I/O hooks.
116 AkUInt32 uRequestedSize; ///< Exact number of requested bytes for this transfer. Always equal to or smaller than uBufferSize.
120 /// Callback function prototype definition used for asynchronous I/O transfers between the Stream Manager
123 /// - 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.
124 /// - If the transfer was cancelled by the Stream Manager while it was in the Low-Level IO, you must return AK_Success, whether
125 /// 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.
130 AkAsyncIOTransferInfo * in_pTransferInfo, ///< Pointer to the AkAsyncIOTransferInfo structure that was passed to corresponding Read() or Write() call.
131 AKRESULT in_eResult ///< Result of transfer: AK_Success or AK_Fail (streams waiting for this transfer become invalid).
134 /// Structure for asynchronous transfers handshaking with the Low-Level I/O. Extends AkIOTransferInfo.
142 AkIOCallback pCallback; ///< Callback function used to notify the high-level device when the transfer is complete.
143 void * pCookie; ///< Reserved. The I/O device uses this cookie to retrieve the owner of the transfer.
157 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.
166 // Audiokinetic Stream Manager's implementation-specific interfaces of the Low-Level IO submodule.
239 /// Read data from the file described by in_fileDesc, in address out_pBuffer and with size and position
240 /// passed within io_transferInfo. When transfer is complete, return with the proper return code.
244 /// device as "in_fileDesc.uSector * Block_Size + Stream_Position", where Block_Size is obtained
257 /// Write data to the file described by in_fileDesc, from address in_pData and with size and position
258 /// passed within io_transferInfo. When transfer is complete, return with the proper return code.
261 /// device as "in_fileDesc.uSector * Block_Size + Stream_Position", where Block_Size is obtained
277 /// I/O streaming technology. You will receive up to AkDeviceSettings::uMaxConcurrentIO requests
278 /// at the same time. You may queue them into your own system, and even use the heuristics passed
288 /// Cancel() is provided in order to inform you that the streaming device will flush this transfer
300 /// - Queue up your read request with address, size and file position specified in io_transferInfo.
310 /// device as "in_fileDesc.uSector * Block_Size + Stream_Position", where Block_Size is obtained
324 /// - Queue up your write request with address, size and file position specified in io_transferInfo.
326 /// AkAsyncIOTransferInfo::pCallback. However, if you return AK_Fail() from Write(), do not call
334 /// device as "in_fileDesc.uSector * Block_Size + Stream_Position", where Block_Size is obtained
346 /// Notifies that a transfer request is cancelled. It will be flushed by the streaming device when completed.
347 /// Cancellation is normal and happens regularly; for example, whenever a sound stops before the end
348 /// or stops looping. It happens even more frequently when buffering (AkDeviceSettings::fTargetAutoStmBufferLength
349 /// and AkDeviceSettings::uGranularity) is large and when you low-level IO hook accepts many concurrent requests
352 /// - Cancel() simply informs the Low-Level I/O that a specific transfer will be flushed upon reception.
353 /// The Low-Level I/O may use this information to stop this transfer right away, or not (it is internally tagged
354 /// by the high-level device as cancelled). Nevertheless, the callback function MUST be called for cancelled
356 /// - When calling the callback function of a cancelled transfer, pass it *AK_Success*. Passing AK_Fail
357 /// to AkAsyncIOTransfer::pCallback has the effect of killing the stream once and for all. This is not
359 /// - If io_bCancelAllTransfersForThisFile is set, you may cancel all transfers for this file at once.
360 /// Leave io_bCancelAllTransfersForThisFile to true if you don't want to be called again. For example, if
361 /// you don't do anything special in Cancel(), leave it to true. This will reduce the amount of useless calls.
362 /// If you set it to false, Cancel() will be called again for each remaining pending transfer that need to be cancelled.
363 /// - If io_bCancelAllTransfersForThisFile is not set, Cancel() is only called for a subset of pending
364 /// 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.
366 /// - The calling thread holds the stream's lock. You may call the callback function directly from here
367 /// (if you can guarantee that the I/O buffer will not be accessed in the meantime), but you must not wait here
369 /// - Likewise, if you resolve transfers with your own thread and use a lock to protect your transfers queue,
370 /// be careful not to run into a deadlock. Cancel() can be executed by any thread. Thus, if you need to lock your queue
371 /// in Cancel(), you must never hold this lock when calling back transfers, either from within Cancel() or from your
372 /// worker thread's routine. Lock your list, dequeue the transfer if you can, unlock, and call pCallback if and only if
373 /// the transfer was found and dequeued. On the other hand, if you choose not to do anything in Cancel(), the lock only protects
374 /// your list between Read()/Write() and your worker thread's routine, and since the device I/O thread does not hold the
375 /// stream's lock while calling Read()/Write(), your worker thread may therefore hold it while calling back transfers.
376 /// - A race condition exists when cancelling all transfers (io_bCancelAllTransfersForThisFile is true) directly from within this hook.
377 /// If you handle the io_bCancelAllTransfersForThisFile == true case, you need to defer calling the completion callback to later
378 /// (from your usual I/O completion thread, for example). This will be fixed in a future version of Wwise.
382 bool & io_bCancelAllTransfersForThisFile ///< Flag indicating whether all transfers should be cancelled for this file (see notes in function description).
387 /// registered to the Stream Manager (using AK::StreamMgr::SetFileLocationResolver()). Its purpose
395 /// If you wish to create multiple devices, then you should have a separate object that implements
396 /// AK::StreamMgr::IAkFileLocationResolver and registers to the Stream Manager as such. This object
397 /// will be used to dispatch the file open request to the appropriate device. The strategy you will
454 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.
505 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.
533 AkStreamMgrSettings & out_settings ///< Returned AkStreamMgrSettings structure with default values.
546 IAkFileLocationResolver * in_pFileLocationResolver ///< Interface to your File Location Resolver
564 /// \return The device ID. AK_INVALID_DEVICE_ID if there was an error and it could not be created.
570 /// statically cast internally into one of these hooks. Implementing the wrong (or no) interface
575 /// - The returned device ID should be kept by the Low-Level IO, to assign it to file descriptors
583 IAkLowLevelIOHook * in_pLowLevelHook ///< Associated low-level I/O hook. Pass either a IAkIOHookBlocking or a IAkIOHookDeferred interface, consistent with the type of the scheduler.
587 /// \warning This function is not thread-safe. No stream should exist for that device when it is destroyed.
605 /// Set the current language once and only once, here. The language name is stored in a static buffer
607 /// AK::StreamMgr::IAkFileLocationResolver implementations query this string. They may use it to
608 /// construct a file path (for e.g. SDK/samples/SoundEngine/Common/AkFileLocationBase.cpp), or to
609 /// find a language-specific file within a look-up table (for e.g. SDK/samples/SoundEngine/Common/AkFilePackageLUT.cpp).
610 /// Pass a valid null-terminated string, without a trailing slash or backslash. Empty strings are accepted.
613 /// \return AK_Success if successful (if language string has less than AK_MAX_LANGUAGE_NAME_SIZE characters). AK_Fail otherwise.
622 /// Get the current language. The language name is stored in a static buffer inside the Stream Manager,
623 /// with AK::StreamMgr::SetCurrentLanguage(). In order to resolve localized (language-specific) file location,
624 /// AK::StreamMgr::IAkFileLocationResolver implementations query this string. They may use it to
625 /// construct a file path (for e.g. SDK/samples/SoundEngine/Common/AkFileLocationBase.cpp), or to
626 /// find a language-specific file within a look-up table (for e.g. SDK/samples/SoundEngine/Common/AkFilePackageLUT.cpp).
633 /// \warning Do not call AddLanguageChangeObserver or SetCurrentLanguage from within your handler.
virtual ~IAkIOHookBlocking()
Virtual destructor on interface to avoid warnings.
Definition: AkStreamMgrModule.h:234
AkUInt32 uBufferSize
Size of the buffer in which the I/O hook can write to.
Definition: AkStreamMgrModule.h:115
virtual ~IAkLowLevelIOHook()
Virtual destructor on interface to avoid warnings.
Definition: AkStreamMgrModule.h:174
virtual AKRESULT Read(AkFileDesc &in_fileDesc, const AkIoHeuristics &in_heuristics, AkAsyncIOTransferInfo &io_transferInfo)=0
virtual void Cancel(AkFileDesc &in_fileDesc, AkAsyncIOTransferInfo &io_transferInfo, bool &io_bCancelAllTransfersForThisFile)=0
AkUInt32 uGranularity
I/O requests granularity (typical bytes/request).
Definition: AkStreamMgrModule.h:75
Definition: AkStreamMgrModule.h:112
void(* AkIOCallback)(AkAsyncIOTransferInfo *in_pTransferInfo, AKRESULT in_eResult)
Definition: AkStreamMgrModule.h:129
Definition: AkStreamMgrModule.h:50
AKRESULT __cdecl AddLanguageChangeObserver(AkLanguageChangeHandler in_handler, void *in_pCookie)
virtual AKRESULT Read(AkFileDesc &in_fileDesc, const AkIoHeuristics &in_heuristics, void *out_pBuffer, AkIOTransferInfo &in_transferInfo)=0
Base interface for Low-Level I/O hooks. Defines common methods across both types of hooks.
Definition: AkStreamMgrModule.h:170
virtual AKRESULT Write(AkFileDesc &in_fileDesc, const AkIoHeuristics &in_heuristics, AkAsyncIOTransferInfo &io_transferInfo)=0
AKRESULT __cdecl DestroyDevice(AkDeviceID in_deviceID)
virtual ~IAkFileLocationResolver()
Virtual destructor on interface to avoid warnings.
Definition: AkStreamMgrModule.h:405
AkUInt32 uRequestedSize
Exact number of requested bytes for this transfer. Always equal to or smaller than uBufferSize.
Definition: AkStreamMgrModule.h:116
virtual AkUInt32 GetDeviceData()=0
void __cdecl FlushAllCaches()
AkDeviceID __cdecl CreateDevice(const AkDeviceSettings &in_settings, IAkLowLevelIOHook *in_pLowLevelHook)
Definition: AkStreamMgrModule.h:139
void __cdecl RemoveLanguageChangeObserver(void *in_pCookie)
virtual AkUInt32 GetBlockSize(AkFileDesc &in_fileDesc)=0
IAkFileLocationResolver *__cdecl GetFileLocationResolver()
AkUInt32 uMaxCachePinnedBytes
Maximum number of bytes that can be "pinned" using AK::SoundEngine::PinEventInStreamCache() or AK::IA...
Definition: AkStreamMgrModule.h:81
AkIOCallback pCallback
Callback function used to notify the high-level device when the transfer is complete.
Definition: AkStreamMgrModule.h:142
AkUInt32 uIOMemorySize
Size of memory pool for I/O (for automatic streams). It is passed directly to AK::MemoryMgr::CreatePo...
Definition: AkStreamMgrModule.h:72
void __cdecl SetFileLocationResolver(IAkFileLocationResolver *in_pFileLocationResolver)
AkMemPoolId __cdecl GetPoolID()
AkMemPoolAttributes ePoolAttributes
Attributes for internal I/O memory pool. Note that these pools are always allocated internally as AkF...
Definition: AkStreamMgrModule.h:74
bool bUseStreamCache
If true the device attempts to reuse IO buffers that have already been streamed from disk....
Definition: AkStreamMgrModule.h:80
Definition: AkPlatformFuncs.h:48
Definition: AkStreamMgrModule.h:67
virtual ~IAkIOHookDeferred()
Virtual destructor on interface to avoid warnings.
Definition: AkStreamMgrModule.h:294
virtual AKRESULT Write(AkFileDesc &in_fileDesc, const AkIoHeuristics &in_heuristics, void *in_pData, AkIOTransferInfo &io_transferInfo)=0
virtual AKRESULT Open(const AkOSChar *in_pszFileName, AkOpenMode in_eOpenMode, AkFileSystemFlags *in_pFlags, bool &io_bSyncOpen, AkFileDesc &io_fileDesc)=0
Definition: AkStreamMgrModule.h:97
void(* AkLanguageChangeHandler)(const AkOSChar *const in_pLanguageName, void *in_pCookie)
Definition: AkStreamMgrModule.h:638
virtual void GetDeviceDesc(AkDeviceDesc &out_deviceDesc)=0
AKRESULT __cdecl SetCurrentLanguage(const AkOSChar *in_pszLanguageName)
void __cdecl GetDefaultDeviceSettings(AkDeviceSettings &out_settings)
virtual AKRESULT Close(AkFileDesc &in_fileDesc)=0
Definition: IAkStreamMgr.h:661
AkReal32 fTargetAutoStmBufferLength
Targetted automatic stream buffer length (ms). When a stream reaches that buffering,...
Definition: AkStreamMgrModule.h:78
void __cdecl GetDefaultSettings(AkStreamMgrSettings &out_settings)
const AkOSChar *__cdecl GetCurrentLanguage()
Definition: AkStreamMgrModule.h:154
void * pCookie
Reserved. The I/O device uses this cookie to retrieve the owner of the transfer.
Definition: AkStreamMgrModule.h:143
AkUInt32 uMaxConcurrentIO
Maximum number of transfers that can be sent simultaneously to the Low-Level I/O (applies to AK_SCHED...
Definition: AkStreamMgrModule.h:79
AkUInt32 uIOMemoryAlignment
I/O memory pool alignment. It is passed directly to AK::MemoryMgr::CreatePool().
Definition: AkStreamMgrModule.h:73
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:157
IAkStreamMgr *__cdecl Create(const AkStreamMgrSettings &in_settings)
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