Wwise SDK 2018.1.11
_ak_stream_mgr_module_8h_source
版本
menu_open
link
Wwise SDK 2018.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
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)