Wwise SDK
_ak_stream_mgr_module_8h_source
Version
menu_open
Wwise SDK 2023.1.5
|
AkStreamMgrModule.h
Go to the documentation of this file.
30 /// Contains the default Stream Manager's implementation-specific interfaces that altogether constitute
31 /// the Low-Level I/O submodule. This submodule needs to be implemented by the game. All I/O requests
63 AkUInt32 uIOMemorySize; ///< Size of memory for I/O (for automatic streams). It is passed directly to AK::MemoryMgr::Malign(), after having been rounded down to a multiple of uGranularity.
64 AkUInt32 uIOMemoryAlignment; ///< I/O memory alignment. It is passed directly to AK::MemoryMgr::Malign().
65 AkUInt32 ePoolAttributes; ///< Attributes for I/O memory. Here, specify the allocation type (AkMemType_Device, and so on). It is passed directly to AK::MemoryMgr::Malign().
68 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.
69 AkUInt32 uMaxConcurrentIO; ///< Maximum number of transfers that can be sent simultaneously to the Low-Level I/O.
70 bool bUseStreamCache; ///< If true, the device attempts to reuse I/O buffers that have already been streamed from disk. This is particularly useful when streaming small looping sounds. However, there is a small increase in CPU usage when allocating memory, and a slightly larger memory footprint in the StreamManager pool.
71 AkUInt32 uMaxCachePinnedBytes; ///< Maximum number of bytes that can be "pinned" using AK::SoundEngine::PinEventInStreamCache() or AK::IAkStreamMgr::PinFileInCache()
87 AkDeviceID deviceID = AK_INVALID_DEVICE_ID; ///< Device ID, obtained from CreateDevice() \sa AK::IAkStreamMgr::CreateDevice()
90 /// Structure for synchronous transfers handshaking with the Low-Level I/O. Used with blocking I/O hooks.
96 AkUInt32 uRequestedSize; ///< Exact number of requested bytes for this transfer. Always equal to or smaller than uBufferSize.
101 /// Callback function prototype definition used for asynchronous I/O transfers between the Stream Manager and the Low-Level IO.
103 /// - If you pass in_eResult of 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.
104 /// - If the transfer was cancelled by the Stream Manager while it was in the Low-Level IO, you must return AK_Success, whether
105 /// 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.
110 AkAsyncIOTransferInfo * in_pTransferInfo, ///< Pointer to the AkAsyncIOTransferInfo structure that was passed to corresponding Read() or Write() call.
111 AKRESULT in_eResult ///< Result of transfer: AK_Success or AK_Fail (streams waiting for this transfer become invalid).
114 /// Structure for asynchronous transfers handshaking with the Low-Level I/O. Extends AkIOTransferInfo.
122 AkIOCallback pCallback; ///< Callback function used to notify the high-level device when the transfer is complete.
123 void * pCookie; ///< Reserved. The I/O device uses this cookie to retrieve the owner of the transfer.
134 AkAsyncFileOpenData * in_pOpenInfo, ///< Pointer to the AkAsyncFileOpenData structure that was passed to corresponding Open().
135 AKRESULT in_eResult ///< Result of transfer: AK_Success or AK_Fail (streams waiting for this transfer become invalid).
138 /// Structure used by Low Level IO Hooks (IAkLowLevelIOHook) to pass and retreive information on files to be opened by the IO hook.
139 /// Please refer to AK::StreamMgr::IAkLowLevelIOHook::BatchOpen for more information about the sementics of the Open operation.
176 AkAsyncFileOpenData(const AkOSChar* in_pszFileName, AkOpenMode in_eOpenMode = AK_OpenModeRead, AkFileSystemFlags* in_pFlags = NULL)
185 AkAsyncFileOpenData(AkFileID in_idFile, AkOpenMode in_eOpenMode = AK_OpenModeRead, AkFileSystemFlags* in_pFlags = NULL)
194 ///< Functions used to manage optional stream name. The name will be used when sending stream information to the Wwise profiler.
198 AkFileOpenCallback pCallback; ///< Callback function used to notify the high-level device when Open is done
199 void* pCookie; ///< Reserved. Pass this unchanged to the callback function. The I/O device uses this cookie to retrieve the owner of the transfer.
201 void* pCustomData; ///< Convienience pointer for the IO hook implementer. Useful for additional data used in asynchronous implementations, for example.
204 AkOSChar* pszStreamName; ///< Display name. If provided, this will be used to set the stream name, which is used for the profiler. This struct is not responsible for the memory.
215 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.
223 /// Audiokinetic Stream Manager's implementation-specific interfaces of the Low-Level IO submodule.
231 /// from the main audio thread. Also, it is assumed that all operations are asynchronous although
242 /// Cancel() is provided in order to inform you that the streaming device will flush this transfer
311 /// - It is possible to mix synchronous and asynchronous file opens, as long as all pCallbacks are eventually called.
312 /// - When implementing this function, make sure to process all items even if one fails to be dispatched or to open.
313 /// - Pointers in in_ppItems will stay valid until pCallback is called to signal the operation result.
321 /// - Queue up multiple read requests at once, using the provided array of in_pTransferItems. There will
323 /// - The pCallback within each BatchIoTransferItem::pTransferInfo must be called when completed.
325 /// device is notified through the callback. However, the array of in_pTransferItems will not be valid.
326 /// - File position passed in each BatchIoTransferItem::pTransferInfo takes the offset of this file relative
337 /// - Queue up multiple write requests at once, using the provided array of in_pTransferItems. There will
339 /// - The pCallback within each BatchIoTransferItem::pTransferInfo must be called when completed.
341 /// device is notified through the callback. However, the array of in_pTransferItems will not be valid.
342 /// - File position passed in each BatchIoTransferItem::pTransferInfo takes the offset of this file relative
351 /// Notifies that a transfer request is cancelled. It will be flushed by the streaming device when completed.
352 /// Cancellation is normal and happens regularly; for example, whenever a sound stops before the end
353 /// or stops looping. It happens even more frequently when buffering (AkDeviceSettings::fTargetAutoStmBufferLength
354 /// and AkDeviceSettings::uGranularity) is large and when you low-level IO hook accepts many concurrent requests
358 /// - BatchCancel() simply informs the Low-Level I/O that a specific transfer will be flushed upon reception.
359 /// The Low-Level I/O may use this information to stop this transfer right away, or not (it is internally tagged
360 /// by the high-level device as cancelled). Nevertheless, the callback function MUST be called for cancelled
362 /// - When calling the callback function of a cancelled transfer, pass it *AK_Success*. Passing AK_Fail
363 /// to AkAsyncIOTransfer::pCallback has the effect of killing the stream once and for all. This is not
365 /// - If io_bCancelAllTransfersForThisFile is set, you may cancel all transfers for this file at once.
366 /// Leave io_bCancelAllTransfersForThisFile to true if you don't want to be called again. For example, if
367 /// you don't do anything special in BatchCancel(), leave it to true. This will reduce the amount of useless calls.
368 /// If you set it to false, BatchCancel() will be called again for each remaining pending transfer that need to be cancelled.
369 /// - If io_bCancelAllTransfersForThisFile is not set, BatchCancel() is only called for a subset of pending
370 /// transfers for this file. You must not set it to true, as BatchCancel() needs to be called explicitly for each transfer that
373 /// - The calling thread holds the stream's lock. You may call the callback function directly from here
374 /// (if you can guarantee that the I/O buffer will not be accessed in the meantime), but you must not wait here
376 /// - Likewise, if you resolve transfers with your own thread and use a lock to protect your transfers queue,
377 /// be careful not to run into a deadlock. BatchCancel() can be executed by any thread. Thus, if you need to lock your queue
378 /// in BatchCancel(), you must never hold this lock when calling back transfers, either from within BatchCancel() or from your
379 /// worker thread's routine. Lock your list, dequeue the transfer if you can, unlock, and call pCallback if and only if
380 /// the transfer was found and dequeued. On the other hand, if you choose not to do anything in BatchCancel(), the lock only protects
381 /// your list between Read()/Write() and your worker thread's routine, and since the device I/O thread does not hold the
382 /// stream's lock while calling Read()/Write(), your worker thread may therefore hold it while calling back transfers.
383 /// - A race condition exists when cancelling all transfers (io_bCancelAllTransfersForThisFile is true) directly from within this hook.
384 /// If you handle the io_bCancelAllTransfersForThisFile == true case, you need to defer calling the completion callback to later
385 /// (from your usual I/O completion thread, for example). This will be fixed in a future version of Wwise.
389 bool** io_ppbCancelAllTransfersForThisFile ///< Flag for each transfer indicating whether all transfers should be cancelled for this file (see notes in function description).
392 /// This function is called to provide information when file related errors occur. The base paths known by this IO hook should be returned in out_searchedPath.
396 AkOSChar* out_searchedPath, ///< Pre-allocated string buffer to be filled with all searched paths searched for the file.
402 /// registered to the Stream Manager (using AK::StreamMgr::SetFileLocationResolver()). Its purpose
408 /// If you wish to create multiple devices, then you should have a separate object that implements
409 /// AK::StreamMgr::IAkFileLocationResolver and registers to the Stream Manager as such. This object
410 /// will be used to dispatch the file open request to the appropriate device. The strategy you will
424 /// If your File Resolver only handles one device, return AK_NotImplemented and the StreamMgr will use the only device configured.
425 /// If it handles multiple devices, you can base the decision on where to get the file on any kind of heuristic:
430 /// - AK_Success if there is a device to delegate the Open() call to. io_idDevice should be set to the proper AkDeviceID (as returned by AK::StreamMgr::CreateDevice).
432 /// - AK_NotImplemented if there is only one device in the system and file resolution is trivial.
465 AkStreamMgrSettings & out_settings ///< Returned AkStreamMgrSettings structure with default values.
478 IAkFileLocationResolver * in_pFileLocationResolver ///< Interface to your File Location Resolver
488 /// \return The device ID. AK_INVALID_DEVICE_ID if there was an error and it could not be created.
494 /// - The returned device ID should be kept by the Low-Level IO, to assign it to file descriptors
499 /// - AK_InvalidParameter: One of the settings in AkDeviceSettings is out of range. Check asserts or debug console.
506 IAkLowLevelIOHook * in_pLowLevelHook, ///< Associated low-level I/O hook. Pass either a IAkLowLevelIOHook interface, consistent with the type of the scheduler.
507 AkDeviceID& out_idDevice ///< Assigned unique device id to use in all other functions of this interface.
511 /// \warning This function is not thread-safe. No stream should exist for that device when it is destroyed.
517 /// This should only be called in single-threaded environments where an I/O device cannot spawn a thread.
536 /// Set the current language once and only once, here. The language name is stored in a static buffer
538 /// AK::StreamMgr::IAkFileLocationResolver implementations query this string. They may use it to
539 /// construct a file path (for e.g. SDK/samples/SoundEngine/Common/AkFileLocationBase.cpp), or to
540 /// find a language-specific file within a look-up table (for e.g. SDK/samples/SoundEngine/Common/AkFilePackageLUT.cpp).
541 /// Pass a valid null-terminated string, without a trailing slash or backslash. Empty strings are accepted.
544 /// \return AK_Success if successful (if language string has less than AK_MAX_LANGUAGE_NAME_SIZE characters). AK_Fail otherwise.
553 /// Get the current language. The language name is stored in a static buffer inside the Stream Manager,
554 /// with AK::StreamMgr::SetCurrentLanguage(). In order to resolve localized (language-specific) file location,
555 /// AK::StreamMgr::IAkFileLocationResolver implementations query this string. They may use it to
556 /// construct a file path (for e.g. SDK/samples/SoundEngine/Common/AkFileLocationBase.cpp), or to
557 /// 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:123
AkUInt32 uIOMemoryAlignment
I/O memory alignment. It is passed directly to AK::MemoryMgr::Malign().
Definition: AkStreamMgrModule.h:64
Definition: AkStreamMgrModule.h:120
Definition: AkPlatformFuncs.h:47
Definition: AkStreamMgrModule.h:80
virtual void BatchRead(AkUInt32 in_uNumTransfers, BatchIoTransferItem *in_pTransferItems)=0
AkFileDesc * pFileDesc
Definition: AkStreamMgrModule.h:302
AKSOUNDENGINE_API AKRESULT DestroyDevice(AkDeviceID in_deviceID)
Definition: IAkStreamMgr.h:226
AKSOUNDENGINE_API AKRESULT SetCurrentLanguage(const AkOSChar *in_pszLanguageName)
virtual AkUInt32 GetDeviceData()=0
AkAsyncFileOpenData(AkFileID in_idFile, AkOpenMode in_eOpenMode=AK_OpenModeRead, AkFileSystemFlags *in_pFlags=NULL)
Functions used to manage optional stream name. The name will be used when sending stream information ...
Definition: AkStreamMgrModule.h:185
void(* AkLanguageChangeHandler)(const AkOSChar *const in_pLanguageName, void *in_pCookie)
Definition: AkStreamMgrModule.h:569
AkUInt32 uMaxCachePinnedBytes
Maximum number of bytes that can be "pinned" using AK::SoundEngine::PinEventInStreamCache() or AK::IA...
Definition: AkStreamMgrModule.h:71
AkUInt32 uRequestedSize
Exact number of requested bytes for this transfer. Always equal to or smaller than uBufferSize.
Definition: AkStreamMgrModule.h:96
Definition: IAkStreamMgr.h:725
AkAsyncFileOpenData(const AkFileOpenData &in_copy)
Definition: AkStreamMgrModule.h:147
AkUInt32 uMaxConcurrentIO
Maximum number of transfers that can be sent simultaneously to the Low-Level I/O.
Definition: AkStreamMgrModule.h:69
AkReal32 fTargetAutoStmBufferLength
Targetted automatic stream buffer length (ms). When a stream reaches that buffering,...
Definition: AkStreamMgrModule.h:68
bool bUseStreamCache
If true, the device attempts to reuse I/O buffers that have already been streamed from disk....
Definition: AkStreamMgrModule.h:70
AKSOUNDENGINE_API void GetDefaultSettings(AkStreamMgrSettings &out_settings)
virtual ~IAkLowLevelIOHook()
Virtual destructor on interface to avoid warnings.
Definition: AkStreamMgrModule.h:248
AkAsyncFileOpenData(const AkOSChar *in_pszFileName, AkOpenMode in_eOpenMode=AK_OpenModeRead, AkFileSystemFlags *in_pFlags=NULL)
Definition: AkStreamMgrModule.h:176
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:215
void(* AkIOCallback)(AkAsyncIOTransferInfo *in_pTransferInfo, AKRESULT in_eResult)
Definition: AkStreamMgrModule.h:109
AkUInt32 ePoolAttributes
Attributes for I/O memory. Here, specify the allocation type (AkMemType_Device, and so on)....
Definition: AkStreamMgrModule.h:65
Definition: AkStreamMgrModule.h:59
AkUInt32 uBufferSize
Size of the buffer in which the I/O hook can write to.
Definition: AkStreamMgrModule.h:95
void(* AkFileOpenCallback)(AkAsyncFileOpenData *in_pOpenInfo, AKRESULT in_eResult)
Definition: AkStreamMgrModule.h:133
void * pCookie
Reserved. Pass this unchanged to the callback function. The I/O device uses this cookie to retrieve t...
Definition: AkStreamMgrModule.h:199
void * pCustomData
Convienience pointer for the IO hook implementer. Useful for additional data used in asynchronous imp...
Definition: AkStreamMgrModule.h:201
AkAsyncFileOpenData(const AkAsyncFileOpenData &in_copy)
Definition: AkStreamMgrModule.h:157
AkUInt32 uGranularity
I/O requests granularity (typical bytes/request).
Definition: AkStreamMgrModule.h:66
Definition: AkStreamMgrModule.h:213
virtual void GetDeviceDesc(AkDeviceDesc &out_deviceDesc)=0
AKSOUNDENGINE_API AKRESULT PerformIO()
AkFileOpenCallback pCallback
Callback function used to notify the high-level device when Open is done.
Definition: AkStreamMgrModule.h:198
AKRESULT SetStreamName(const AkOSChar *in_pszStreamName)
virtual void BatchCancel(AkUInt32 in_uNumTransfers, BatchIoTransferItem *in_pTransferItems, bool **io_ppbCancelAllTransfersForThisFile)=0
virtual AKRESULT GetNextPreferredDevice(AkAsyncFileOpenData &in_FileOpen, AkDeviceID &io_idDevice)
Definition: AkStreamMgrModule.h:435
AKSOUNDENGINE_API AKRESULT CreateDevice(const AkDeviceSettings &in_settings, IAkLowLevelIOHook *in_pLowLevelHook, AkDeviceID &out_idDevice)
virtual AKRESULT Close(AkFileDesc *in_pFileDesc)=0
~AkAsyncFileOpenData()
virtual AkUInt32 GetBlockSize(AkFileDesc &in_fileDesc)=0
Definition: AkStreamMgrModule.h:93
const AkOSChar * GetStreamName() const
Definition: AkStreamMgrModule.h:196
Definition: AkStreamMgrModule.h:144
AkIOCallback pCallback
Callback function used to notify the high-level device when the transfer is complete.
Definition: AkStreamMgrModule.h:122
AKSOUNDENGINE_API IAkFileLocationResolver * GetFileLocationResolver()
virtual void BatchWrite(AkUInt32 in_uNumTransfers, BatchIoTransferItem *in_pTransferItems)=0
AKSOUNDENGINE_API IAkStreamMgr * Create(const AkStreamMgrSettings &in_settings)
AKSOUNDENGINE_API void FlushAllCaches()
AkIoHeuristics ioHeuristics
Definition: AkStreamMgrModule.h:303
AKSOUNDENGINE_API void GetDefaultDeviceSettings(AkDeviceSettings &out_settings)
AKSOUNDENGINE_API void SetFileLocationResolver(IAkFileLocationResolver *in_pFileLocationResolver)
AkFileDesc * pFileDesc
File Descriptor to fill once the Open operation is complete.
Definition: AkStreamMgrModule.h:200
virtual void BatchOpen(AkUInt32 in_uNumFiles, AkAsyncFileOpenData **in_ppItems)=0
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:419
AkUInt32 uIOMemorySize
Size of memory for I/O (for automatic streams). It is passed directly to AK::MemoryMgr::Malign(),...
Definition: AkStreamMgrModule.h:63
Definition: AkStreamMgrModule.h:50
virtual AKRESULT OutputSearchedPaths(AKRESULT in_result, const AkFileOpenData &in_FileOpen, AkOSChar *out_searchedPath, AkInt32 in_pathSize)
This function is called to provide information when file related errors occur. The base paths known b...
Definition: AkStreamMgrModule.h:393
AkAsyncIOTransferInfo * pTransferInfo
Definition: AkStreamMgrModule.h:304
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