Wwise SDK
_ak_stream_mgr_module_8h_source
版本
menu_open
link
Wwise SDK 2023.1.3
|
AkStreamMgrModule.h
浏览该文件的文档.
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.
466 AkStreamMgrSettings & out_settings ///< Returned AkStreamMgrSettings structure with default values.
479 IAkFileLocationResolver * in_pFileLocationResolver ///< Interface to your File Location Resolver
489 /// \return The device ID. AK_INVALID_DEVICE_ID if there was an error and it could not be created.
495 /// - The returned device ID should be kept by the Low-Level IO, to assign it to file descriptors
500 /// - AK_InvalidParameter: One of the settings in AkDeviceSettings is out of range. Check asserts or debug console.
507 IAkLowLevelIOHook * in_pLowLevelHook, ///< Associated low-level I/O hook. Pass either a IAkLowLevelIOHook interface, consistent with the type of the scheduler.
508 AkDeviceID& out_idDevice ///< Assigned unique device id to use in all other functions of this interface.
512 /// \warning This function is not thread-safe. No stream should exist for that device when it is destroyed.
518 /// This should only be called in single-threaded environments where an I/O device cannot spawn a thread.
537 /// Set the current language once and only once, here. The language name is stored in a static buffer
539 /// AK::StreamMgr::IAkFileLocationResolver implementations query this string. They may use it to
540 /// construct a file path (for e.g. SDK/samples/SoundEngine/Common/AkFileLocationBase.cpp), or to
541 /// find a language-specific file within a look-up table (for e.g. SDK/samples/SoundEngine/Common/AkFilePackageLUT.cpp).
542 /// Pass a valid null-terminated string, without a trailing slash or backslash. Empty strings are accepted.
545 /// \return AK_Success if successful (if language string has less than AK_MAX_LANGUAGE_NAME_SIZE characters). AK_Fail otherwise.
554 /// Get the current language. The language name is stored in a static buffer inside the Stream Manager,
555 /// with AK::StreamMgr::SetCurrentLanguage(). In order to resolve localized (language-specific) file location,
556 /// AK::StreamMgr::IAkFileLocationResolver implementations query this string. They may use it to
557 /// construct a file path (for e.g. SDK/samples/SoundEngine/Common/AkFileLocationBase.cpp), or to
558 /// 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:570
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:436
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()