Version
menu_open
link
Wwise SDK 2023.1.3
AkStreamMgrModule.h
Go to the documentation of this file.
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Copyright (c) 2024 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 /// \file
28 /// Audiokinetic's implementation-specific definitions and factory of
29 /// overridable Stream Manager module.
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
32 /// generated by the Stream Manager end up to one of the I/O hooks defined herein.
33 /// Read \ref streamingmanager_lowlevel to learn more about the Low-Level I/O.
34 
35 #ifndef _AK_STREAM_MGR_MODULE_H_
36 #define _AK_STREAM_MGR_MODULE_H_
37 
38 #include <AK/SoundEngine/Common/IAkStreamMgr.h>
39 #include <AK/Tools/Common/AkPlatformFuncs.h>
40 
41 /// \name Audiokinetic Stream Manager's implementation-specific definitions.
42 //@{
43 /// Stream Manager initialization settings.
44 /// \sa
45 /// - AK::IAkStreamMgr
46 /// - AK::StreamMgr::Create()
47 /// - \ref streamingmanager_settings
48 
49 struct AkStreamMgrSettings
50 {
51 };
52 
53 /// High-level IO devices initialization settings.
54 /// \sa
55 /// - AK::IAkStreamMgr
56 /// - AK::StreamMgr::CreateDevice()
57 /// - \ref streamingmanager_settings
58 struct AkDeviceSettings
59 {
60  void * pIOMemory; ///< Pointer for I/O memory allocated by user.
61  ///< Pass NULL if you want memory to be allocated via AK::MemoryMgr::Malign().
62  ///< If specified, uIOMemorySize, uIOMemoryAlignment and ePoolAttributes are ignored.
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().
66  AkUInt32 uGranularity; ///< I/O requests granularity (typical bytes/request).
67  AkThreadProperties threadProperties; ///< Scheduler thread properties.
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()
72 };
73 
74 /// File descriptor. File identification for the low-level I/O.
75 /// \sa
76 /// - AK::StreamMgr::IAkLowLevelIOHook
77 /// - AK::StreamMgr::IAkLowLevelIOHook::BatchOpen
78 /// - AK::StreamMgr::IAkLowLevelIOHook::Close
79 struct AkFileDesc
80 {
81  AkInt64 iFileSize = 0; ///< File size in bytes
82  AkUInt64 uSector = 0; ///< Start sector (the sector size is specified by the low-level I/O)
83  ///< \sa
84  ///< - AK::StreamMgr::IAkFileLocationResolver::Open()
85  ///< - AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize()
86  AkFileHandle hFile = AkFileHandle(); ///< File handle/identifier
87  AkDeviceID deviceID = AK_INVALID_DEVICE_ID; ///< Device ID, obtained from CreateDevice() \sa AK::IAkStreamMgr::CreateDevice()
88 };
89 
90 /// Structure for synchronous transfers handshaking with the Low-Level I/O. Used with blocking I/O hooks.
91 /// \sa AK::StreamMgr::IAkLowLevelIOHook
92 struct AkIOTransferInfo
93 {
94  AkUInt64 uFilePosition; ///< File offset where transfer should begin.
95  AkUInt32 uBufferSize; ///< Size of the buffer in which the I/O hook can write to.
96  AkUInt32 uRequestedSize; ///< Exact number of requested bytes for this transfer. Always equal to or smaller than uBufferSize.
97 };
98 
99 struct AkAsyncIOTransferInfo;
100 
101 /// Callback function prototype definition used for asynchronous I/O transfers between the Stream Manager and the Low-Level IO.
102 /// Notes:
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.
106 /// \sa
107 /// - AkAsyncIOTransferInfo
108 /// - AK::StreamMgr::IAkLowLevelIOHook
109 AK_CALLBACK( void, AkIOCallback )(
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).
112  );
113 
114 /// Structure for asynchronous transfers handshaking with the Low-Level I/O. Extends AkIOTransferInfo.
115 /// \sa
116 /// - AK::StreamMgr::IAkLowLevelIOHook
117 /// - AkIOTransferInfo
118 /// - AkAIOCallback
119 struct AkAsyncIOTransferInfo : public AkIOTransferInfo
120 {
121  void * pBuffer; ///< Buffer for data transfer.
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.
124  void * pUserData; ///< Custom user data.
125 };
126 
127 struct AkAsyncFileOpenData;
128 
129 /// Callback signature for the notification of completion of the asynchronous Open operation.
130 /// \sa
131 /// - AkAsyncFileOpenData
132 /// - AK::StreamMgr::IAkLowLevelIOHook::BatchOpen
133 AK_CALLBACK(void, AkFileOpenCallback)(
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).
136  );
137 
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.
140 /// \sa
141 /// - AkFileOpenData
142 /// - AK::StreamMgr::IAkLowLevelIOHook::BatchOpen
143 struct AkAsyncFileOpenData : public AkFileOpenData
144 {
145  ~AkAsyncFileOpenData();
146 
147  AkAsyncFileOpenData(const AkFileOpenData& in_copy)
148  : pCallback(NULL)
149  , pCookie(NULL)
150  , pFileDesc(NULL)
151  , pCustomData(NULL)
152  , pszStreamName(NULL)
153  {
154  *(AkFileOpenData*)this = in_copy;
155  }
156 
157  AkAsyncFileOpenData(const AkAsyncFileOpenData& in_copy)
158  : pCallback(in_copy.pCallback)
159  , pCookie(in_copy.pCookie)
160  , pFileDesc(in_copy.pFileDesc)
161  , pCustomData(NULL)
162  , pszStreamName(NULL)
163  {
164  *(AkFileOpenData*)this = in_copy;
165  }
166 
167  AkAsyncFileOpenData()
168  : AkFileOpenData()
169  , pCallback(NULL)
170  , pCookie(NULL)
171  , pFileDesc(NULL)
172  , pCustomData(NULL)
173  , pszStreamName(NULL)
174  {}
175 
176  AkAsyncFileOpenData(const AkOSChar* in_pszFileName, AkOpenMode in_eOpenMode = AK_OpenModeRead, AkFileSystemFlags* in_pFlags = NULL)
177  :AkFileOpenData(in_pszFileName, in_eOpenMode, in_pFlags)
178  , pCallback(NULL)
179  , pCookie(NULL)
180  , pFileDesc(NULL)
181  , pCustomData(NULL)
182  , pszStreamName(NULL)
183  {}
184 
185  AkAsyncFileOpenData(AkFileID in_idFile, AkOpenMode in_eOpenMode = AK_OpenModeRead, AkFileSystemFlags* in_pFlags = NULL)
186  :AkFileOpenData(in_idFile, in_eOpenMode, in_pFlags)
187  , pCallback(NULL)
188  , pCookie(NULL)
189  , pFileDesc(NULL)
190  , pCustomData(NULL)
191  , pszStreamName(NULL)
192  {}
193 
194  ///< Functions used to manage optional stream name. The name will be used when sending stream information to the Wwise profiler.
195  AKRESULT SetStreamName(const AkOSChar* in_pszStreamName);
196  const AkOSChar* GetStreamName() const { return pszStreamName; }
197 
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.
200  AkFileDesc* pFileDesc; ///< File Descriptor to fill once the Open operation is complete.
201  void* pCustomData; ///< Convienience pointer for the IO hook implementer. Useful for additional data used in asynchronous implementations, for example.
202 
203 private:
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.
205 };
206 
207 /// Low-Level I/O requests heuristics.
208 /// Used for asynchronous read requests.
209 /// \sa
210 /// - AK::StreamMgr::IAkLowLevelIOHook::BatchRead()
211 /// - AK::StreamMgr::IAkLowLevelIOHook::BatchWrite()
212 struct AkIoHeuristics
213 {
214  AkReal32 fDeadline; ///< Operation deadline (ms).
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.
216 };
217 
218 
219 //@}
220 
221 namespace AK
222 {
223  /// Audiokinetic Stream Manager's implementation-specific interfaces of the Low-Level IO submodule.
224  namespace StreamMgr
225  {
226  /// Interface for batched deferred low-level I/O transfers.
227  /// This I/O transfer handshaking method is preferred when you want to hook I/O to your own
228  /// I/O streaming technology, and you want to submit multiple I/O requests in one call, so as
229  /// to allow for better opportunities for CPU and I/O performance.
230  /// All operations in this interface will be happening in the device's own thread, separate
231  /// from the main audio thread. Also, it is assumed that all operations are asynchronous although
232  /// immediate resolution is also supported.
233  /// You may queue them into your own system, and even use the heuristics passed down to this
234  /// level for your convenience. Note that the requests are always sent in the order that the
235  /// Stream Manager considers to be the most appropriate. You may receive less than
236  /// AkDeviceSettings::uMaxConcurrentIO at any given time. The number of concurrent transfers
237  /// depends on the number of streams running in the high-level streaming device, and on its
238  /// target buffering length and granularity. Your advantage at this level is to be aware of
239  /// file placement, so you may try to re-order requests in order to minimize seeking on disk.
240  /// Calls to BatchRead()/BatchWrite() should return as soon as possible. You need to call
241  /// AkAsyncIOTransferInfo::pCallback for all individual items in a transfer batch.
242  /// Cancel() is provided in order to inform you that the streaming device will flush this transfer
243  /// upon completion. You may implement it or not. In all cases, you must call the callback.
244  class IAkLowLevelIOHook
245  {
246  protected:
247  /// Virtual destructor on interface to avoid warnings.
248  virtual ~IAkLowLevelIOHook(){}
249 
250  public:
251 
252  /// Closes a file.
253  /// The file descriptor should be deleted during this call.
254  /// No other module should have a reference to it at this point.
255  /// \return AK_Success if the file was properly cleaned-up.
256  virtual AKRESULT Close(
257  AkFileDesc * in_pFileDesc ///< File descriptor.
258  ) = 0;
259 
260  /// Returns the block size for the file or its storage device.
261  /// The block size is a constraint for clients
262  /// of the Stream Manager: All reads, writes and position changes need to be a multiple of
263  /// that size.
264  /// \return
265  /// The block size for a specific file or storage device.
266  /// \remarks
267  /// - Some files might be opened with flags that require I/O transfers to be a multiple
268  /// of this size. The stream manager will query this function to resolve calls
269  /// to IAk(Auto)Stream::GetBlockSize( ).
270  /// - Also, AkFileDesc::uSector specifies a number of sectors in multiples of this value.
271  /// - Files/IO devices that do not require byte alignment should return 1.
272  /// - Whether file opening was deferred or not, GetBlockSize() is always called right
273  /// after the first call to Open(), in the client's thread, and is never called again.
274  /// \warning
275  /// Returning 0 is not allowed and will likely make the Stream Manager crash.
276  /// \sa
277  /// - AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()
278  /// - AK::StreamMgr::IAkLowLevelIOHook::BatchRead()
279  /// - AK::StreamMgr::IAkLowLevelIOHook::BatchWrite()
280  virtual AkUInt32 GetBlockSize(
281  AkFileDesc & in_fileDesc ///< File descriptor.
282  ) = 0;
283 
284  /// Returns a description for the streaming device above this low-level hook.
285  /// \remarks For profiling purposes only. The Release configuration of the
286  /// Stream Manager never calls it.
287  virtual void GetDeviceDesc(
288  AkDeviceDesc & out_deviceDesc ///< Device description.
289  ) = 0;
290 
291  /// Returns custom profiling data for the streaming device above this low-level hook.
292  /// As opposed to GetDeviceDesc(), this is called at every monitoring frame.
293  /// You may implement this function in order to display any value you find useful
294  /// in the "Streaming Devices" tab of the Wwise profiler ("Custom Param" column).
295  /// \remarks For profiling purposes only. The Release configuration of the
296  /// Stream Manager never calls it.
297  /// \return A 32-bit unsigned value to display in the Wwise profiler.
298  virtual AkUInt32 GetDeviceData() = 0;
299 
300  struct BatchIoTransferItem
301  {
302  AkFileDesc* pFileDesc;
303  AkIoHeuristics ioHeuristics;
304  AkAsyncIOTransferInfo* pTransferInfo;
305  };
306 
307 
308  /// Request to open multiple files (asynchronous).
309  /// \remarks
310  /// - The pCallback within each AkAsyncFileOpenData must be called when completed.
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.
314  virtual void BatchOpen(
315  AkUInt32 in_uNumFiles, ///< Number of transfers to process
316  AkAsyncFileOpenData** in_ppItems ///< List of files to open. See remarks above.
317  ) = 0;
318 
319  /// Reads multiple data from multiple files (asynchronous).
320  /// \remarks
321  /// - Queue up multiple read requests at once, using the provided array of in_pTransferItems. There will
322  /// be in_uNumTransfers number of items in the array.
323  /// - The pCallback within each BatchIoTransferItem::pTransferInfo must be called when completed.
324  /// - The pointer to each BatchIoTransferItem::pTransferInfo will be valid until the high-level
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
327  /// to AkFileDesc::hFile (described with AkFileDesc::uSector). It is computed by the high-level
328  /// device as "pFileDesc->uSector * Block_Size + Stream_Position", where Block_Size is obtained
329  /// via AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize().
330  virtual void BatchRead(
331  AkUInt32 in_uNumTransfers, ///< Number of transfers to process
332  BatchIoTransferItem* in_pTransferItems ///< List of transfer items to process
333  ) = 0;
334 
335  /// Write multiple data to multiple files (asynchronous).
336  /// \remarks
337  /// - Queue up multiple write requests at once, using the provided array of in_pTransferItems. There will
338  /// be in_uNumTransfers number of items in the array.
339  /// - The pCallback within each BatchIoTransferItem::pTransferInfo must be called when completed.
340  /// - The pointer to each BatchIoTransferItem::pTransferInfo will be valid until the high-level
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
343  /// to AkFileDesc::hFile (described with AkFileDesc::uSector). It is computed by the high-level
344  /// device as "pFileDesc->uSector * Block_Size + Stream_Position", where Block_Size is obtained
345  /// via AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize().
346  virtual void BatchWrite(
347  AkUInt32 in_uNumTransfers, ///< Number of transfers to process
348  BatchIoTransferItem* in_pTransferItems ///< List of transfer items to process
349  ) = 0;
350 
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
355  /// at the same time.
356  /// \remarks
357  /// - BatchCancel() is an optional functionality that can be implemented as a no-op.
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
361  /// transfers to be resolved.
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
364  /// what you want.
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
371  /// should be cancelled.
372  /// \warning
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
375  /// for another thread to call the callback function.
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.
386  virtual void BatchCancel(
387  AkUInt32 in_uNumTransfers, ///< Number of transfers to process
388  BatchIoTransferItem* in_pTransferItems, ///< List of transfer items to process
389  bool** io_ppbCancelAllTransfersForThisFile ///< Flag for each transfer indicating whether all transfers should be cancelled for this file (see notes in function description).
390  ) = 0;
391 
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.
393  virtual AKRESULT OutputSearchedPaths(
394  AKRESULT in_result, ///< Result of the open call
395  const AkFileOpenData& in_FileOpen, ///< File name and flags passed to the Open call.
396  AkOSChar* out_searchedPath, ///< Pre-allocated string buffer to be filled with all searched paths searched for the file.
397  AkInt32 in_pathSize ///< The maximum size of the string
398  ) { return AK_NotImplemented; };
399  };
400 
401  /// File location resolver interface. There is one and only one File Location Resolver that is
402  /// registered to the Stream Manager (using AK::StreamMgr::SetFileLocationResolver()). Its purpose
403  /// is to resolve a file name or ID to a streaming device (I/O hook) that can handle the file.
404  /// When your Low-Level I/O submodule uses a single device, you should create a standalone I/O
405  /// hook which implements one of the I/O hooks defined above, as well
406  /// as the File Location Resolver. You then register this object to the Stream Manager as the
407  /// File Location Resolver.
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
411  /// use to select the correct device is up to you to implement.
412  /// There is a built-in mechanism of chaining devices through GetNextPreferredDevice().
413  /// If a device can't open a file GetNextPreferredDevice will be called again to get the next
414  /// device to check.
415  class IAkFileLocationResolver
416  {
417  protected:
418  /// Virtual destructor on interface to avoid warnings.
419  virtual ~IAkFileLocationResolver(){}
420 
421  public:
422 
423  /// Determines which device to use to open a file.
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:
426  /// file extension, file name, access rights, CodecID, etc.
427  /// The order in which devices are searched is left to the implementer.
428  /// This function will always be called first with io_idDevice = AK_INVALID_DEVICE_ID.
429  /// \return
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).
431  /// - AK_FileNotFound if all devices have been exhausted.
432  /// - AK_NotImplemented if there is only one device in the system and file resolution is trivial.
433  /// \remark
434  /// This can be called from multiple threads.
435  /// Note that there is a
436  virtual AKRESULT GetNextPreferredDevice(
437  AkAsyncFileOpenData& in_FileOpen, ///< File name and flags passed to the Open call.
438  AkDeviceID& io_idDevice ///< In: last device used. Out: next device to use to open the file
439  )
440  { return AK_NotImplemented; };
441  };
442 
443  /// \name Audiokinetic implementation-specific Stream Manager factory.
444  //@{
445  /// Stream Manager factory.
446  /// \remarks
447  /// - In order for the Stream Manager to work properly, you also need to create
448  /// at least one streaming device (and implement its I/O hook), and register the
449  /// File Location Resolver with AK::StreamMgr::SetFileLocationResolver().
450  /// - Use AK::StreamMgr::GetDefaultSettings(), then modify the settings you want,
451  /// then feed this function with them.
452  /// \sa
453  /// - AK::IAkStreamMgr
454  /// - AK::StreamMgr::SetFileLocationResolver()
455  /// - AK::StreamMgr::GetDefaultSettings()
456  AK_EXTERNAPIFUNC( IAkStreamMgr *, Create )(
457  const AkStreamMgrSettings & in_settings ///< Stream manager initialization settings.
458  );
459 
460  /// Get the default values for the Stream Manager's settings.
461  /// \sa
462  /// - AK::StreamMgr::Create()
463  /// - AkStreamMgrSettings
464  /// - \ref streamingmanager_settings
465  AK_EXTERNAPIFUNC( void, GetDefaultSettings )(
466  AkStreamMgrSettings & out_settings ///< Returned AkStreamMgrSettings structure with default values.
467  );
468 
469  /// Get the one and only File Location Resolver registered to the Stream Manager.
470  /// \sa
471  /// - AK::StreamMgr::IAkFileLocationResolver
472  /// - AK::StreamMgr::SetFileLocationResolver()
473  AK_EXTERNAPIFUNC( IAkFileLocationResolver *, GetFileLocationResolver )();
474 
475  /// Register the one and only File Location Resolver to the Stream Manager.
476  /// \sa
477  /// - AK::StreamMgr::IAkFileLocationResolver
478  AK_EXTERNAPIFUNC( void, SetFileLocationResolver )(
479  IAkFileLocationResolver * in_pFileLocationResolver ///< Interface to your File Location Resolver
480  );
481 
482  //@}
483 
484  /// \name Stream Manager: High-level I/O devices management.
485  //@{
486  /// Streaming device creation.
487  /// Creates a high-level device, with specific settings.
488  /// You need to provide the associated low-level I/O hook, implemented on your side.
489  /// \return The device ID. AK_INVALID_DEVICE_ID if there was an error and it could not be created.
490  /// \warning
491  /// - This function is not thread-safe.
492  /// \remarks
493  /// - You may use AK::StreamMgr::GetDefaultDeviceSettings() first to get default values for the
494  /// settings, change those you want, then feed the structure to this function.
495  /// - The returned device ID should be kept by the Low-Level IO, to assign it to file descriptors
496  /// in AK::StreamMgr::IAkLowLevelIOHook::BatchOpen().
497  /// \return
498  /// - AK_Success: Device was added to the system properly
499  /// - AK_InsufficientMemory: Not enough memory to complete the operation
500  /// - AK_InvalidParameter: One of the settings in AkDeviceSettings is out of range. Check asserts or debug console.
501  /// \sa
502  /// - AK::StreamMgr::IAkLowLevelIOHook
503  /// - AK::StreamMgr::GetDefaultDeviceSettings()
504  /// - \ref streamingmanager_settings
505  AK_EXTERNAPIFUNC( AKRESULT, CreateDevice )(
506  const AkDeviceSettings & in_settings, ///< Device settings.
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.
509  );
510  /// Streaming device destruction.
511  /// \return AK_Success if the device was successfully destroyed.
512  /// \warning This function is not thread-safe. No stream should exist for that device when it is destroyed.
513  AK_EXTERNAPIFUNC( AKRESULT, DestroyDevice )(
514  AkDeviceID in_deviceID ///< Device ID of the device to destroy.
515  );
516 
517  /// Execute pending I/O operations on all created I/O devices.
518  /// This should only be called in single-threaded environments where an I/O device cannot spawn a thread.
519  /// \return AK_Success when called from an appropriate environment, AK_NotCompatible otherwise.
520  /// \sa
521  /// - AK::StreamMgr::CreateDevice()
522  AK_EXTERNAPIFUNC( AKRESULT, PerformIO )();
523 
524  /// Get the default values for the streaming device's settings. Recommended usage
525  /// is to call this function first, then pass the settings to AK::StreamMgr::CreateDevice().
526  /// \sa
527  /// - AK::StreamMgr::CreateDevice()
528  /// - AkDeviceSettings
529  /// - \ref streamingmanager_settings
530  AK_EXTERNAPIFUNC( void, GetDefaultDeviceSettings )(
531  AkDeviceSettings & out_settings ///< Returned AkDeviceSettings structure with default values.
532  );
533  //@}
534 
535  /// \name Language management.
536  //@{
537  /// Set the current language once and only once, here. The language name is stored in a static buffer
538  /// inside the Stream Manager. In order to resolve localized (language-specific) file location,
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.
543  /// You may register for language changes (see RegisterToLanguageChangeNotification()).
544  /// After changing the current language, all observers are notified.
545  /// \return AK_Success if successful (if language string has less than AK_MAX_LANGUAGE_NAME_SIZE characters). AK_Fail otherwise.
546  /// \warning Not multithread safe.
547  /// \sa
548  /// - AK::StreamMgr::GetCurrentLanguage()
549  /// - AK::StreamMgr::AddLanguageChangeObserver()
550  AK_EXTERNAPIFUNC( AKRESULT, SetCurrentLanguage )(
551  const AkOSChar * in_pszLanguageName ///< Language name.
552  );
553 
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).
559  /// \return Current language.
560  /// \sa AK::StreamMgr::SetCurrentLanguage()
561  AK_EXTERNAPIFUNC( const AkOSChar *, GetCurrentLanguage )();
562 
563  /// Definition of handlers for language change notifications.
564  /// Called after SetCurrentLanguage() is called.
565  /// \warning Do not call AddLanguageChangeObserver or SetCurrentLanguage from within your handler.
566  /// \warning Not multithread safe.
567  /// \sa
568  /// - AK::StreamMgr::SetCurrentLanguage()
569  /// - AK::StreamMgr::AddLanguageChangeObserver()
570  AK_CALLBACK( void, AkLanguageChangeHandler )(
571  const AkOSChar * const in_pLanguageName,///< New language name.
572  void * in_pCookie ///< Cookie that was passed to AddLanguageChangeObserver().
573  );
574 
575  /// Register to language change notifications.
576  /// \return AK_Success if successful, AK_Fail otherwise (no memory or no cookie).
577  /// \warning Not multithread safe.
578  /// \sa
579  /// - AK::StreamMgr::SetCurrentLanguage()
580  /// - AK::StreamMgr::RemoveLanguageChangeObserver()
581  AK_EXTERNAPIFUNC( AKRESULT, AddLanguageChangeObserver )(
582  AkLanguageChangeHandler in_handler, ///< Callback function.
583  void * in_pCookie ///< Cookie, passed back to AkLanguageChangeHandler. Must set.
584  );
585 
586  /// Unregister to language change notifications. Use the cookie you have passed to
587  /// AddLanguageChangeObserver() to identify the observer.
588  /// \warning Not multithread safe.
589  /// \sa
590  /// - AK::StreamMgr::SetCurrentLanguage()
591  /// - AK::StreamMgr::AddLanguageChangeObserver()
592  AK_EXTERNAPIFUNC( void, RemoveLanguageChangeObserver )(
593  void * in_pCookie ///< Cookie that was passed to AddLanguageChangeObserver().
594  );
595 
596  /// \name Stream Manager: Cache management.
597  //@{
598  /// Flush cache of all devices. This function has no effect for devices where
599  /// AkDeviceSettings::bUseStreamCache was set to false (no caching).
600  /// \sa
601  /// - \ref streamingmanager_settings
602  AK_EXTERNAPIFUNC( void, FlushAllCaches )();
603 
604  //@}
605  }
606 }
607 
608 #endif //_AK_STREAM_MGR_MODULE_H_
AkAsyncIOTransferInfo::pCookie
void * pCookie
Reserved. The I/O device uses this cookie to retrieve the owner of the transfer.
Definition: AkStreamMgrModule.h:123
AkDeviceSettings::uIOMemoryAlignment
AkUInt32 uIOMemoryAlignment
I/O memory alignment. It is passed directly to AK::MemoryMgr::Malign().
Definition: AkStreamMgrModule.h:64
AkIoHeuristics::fDeadline
AkReal32 fDeadline
Operation deadline (ms).
Definition: AkStreamMgrModule.h:214
AK
Audiokinetic namespace.
Definition: AkWwiseSDKVersion.cs:31
AK::StreamMgr::IAkLowLevelIOHook::BatchRead
virtual void BatchRead(AkUInt32 in_uNumTransfers, BatchIoTransferItem *in_pTransferItems)=0
AK::StreamMgr::DestroyDevice
AKSOUNDENGINE_API AKRESULT DestroyDevice(AkDeviceID in_deviceID)
AK::StreamMgr::SetCurrentLanguage
AKSOUNDENGINE_API AKRESULT SetCurrentLanguage(const AkOSChar *in_pszLanguageName)
AK::StreamMgr::IAkLowLevelIOHook::GetDeviceData
virtual AkUInt32 GetDeviceData()=0
AkAsyncFileOpenData::AkAsyncFileOpenData
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
AK::StreamMgr::AkLanguageChangeHandler
void(* AkLanguageChangeHandler)(const AkOSChar *const in_pLanguageName, void *in_pCookie)
Definition: AkStreamMgrModule.h:570
AkDeviceSettings::uMaxCachePinnedBytes
AkUInt32 uMaxCachePinnedBytes
Maximum number of bytes that can be "pinned" using AK::SoundEngine::PinEventInStreamCache() or AK::IA...
Definition: AkStreamMgrModule.h:71
AkAsyncIOTransferInfo::pUserData
void * pUserData
Custom user data.
Definition: AkStreamMgrModule.h:124
AkIOTransferInfo::uRequestedSize
AkUInt32 uRequestedSize
Exact number of requested bytes for this transfer. Always equal to or smaller than uBufferSize.
Definition: AkStreamMgrModule.h:96
AkAsyncFileOpenData::AkAsyncFileOpenData
AkAsyncFileOpenData(const AkFileOpenData &in_copy)
Definition: AkStreamMgrModule.h:147
AK_EXTERNAPIFUNC
#define AK_EXTERNAPIFUNC(_type, _name)
Definition: AkSoundEngineExport.h:81
AkDeviceSettings::uMaxConcurrentIO
AkUInt32 uMaxConcurrentIO
Maximum number of transfers that can be sent simultaneously to the Low-Level I/O.
Definition: AkStreamMgrModule.h:69
AkDeviceSettings::fTargetAutoStmBufferLength
AkReal32 fTargetAutoStmBufferLength
Targetted automatic stream buffer length (ms). When a stream reaches that buffering,...
Definition: AkStreamMgrModule.h:68
AkDeviceSettings::bUseStreamCache
bool bUseStreamCache
If true, the device attempts to reuse I/O buffers that have already been streamed from disk....
Definition: AkStreamMgrModule.h:70
AK::StreamMgr::GetDefaultSettings
AKSOUNDENGINE_API void GetDefaultSettings(AkStreamMgrSettings &out_settings)
AKRESULT
AKRESULT
Standard function call result.
Definition: AkTypes.h:213
AK_INVALID_DEVICE_ID
static const AkDeviceID AK_INVALID_DEVICE_ID
Invalid streaming device ID.
Definition: AkTypes.h:185
AK::StreamMgr::IAkLowLevelIOHook::~IAkLowLevelIOHook
virtual ~IAkLowLevelIOHook()
Virtual destructor on interface to avoid warnings.
Definition: AkStreamMgrModule.h:248
AkAsyncFileOpenData::AkAsyncFileOpenData
AkAsyncFileOpenData(const AkOSChar *in_pszFileName, AkOpenMode in_eOpenMode=AK_OpenModeRead, AkFileSystemFlags *in_pFlags=NULL)
Definition: AkStreamMgrModule.h:176
AkDeviceID
AkUInt32 AkDeviceID
I/O device ID.
Definition: AkTypes.h:160
AkFileDesc::deviceID
AkDeviceID deviceID
Device ID, obtained from CreateDevice()
Definition: AkStreamMgrModule.h:87
AK_OpenModeRead
@ AK_OpenModeRead
Read-only access.
Definition: IAkStreamMgr.h:73
AkIoHeuristics::priority
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
AkIOCallback
void(* AkIOCallback)(AkAsyncIOTransferInfo *in_pTransferInfo, AKRESULT in_eResult)
Definition: AkStreamMgrModule.h:109
AkOSChar
char AkOSChar
Generic character string.
Definition: AkTypes.h:60
AkDeviceSettings::ePoolAttributes
AkUInt32 ePoolAttributes
Attributes for I/O memory. Here, specify the allocation type (AkMemType_Device, and so on)....
Definition: AkStreamMgrModule.h:65
NULL
#define NULL
Definition: AkTypes.h:46
AkIOTransferInfo::uBufferSize
AkUInt32 uBufferSize
Size of the buffer in which the I/O hook can write to.
Definition: AkStreamMgrModule.h:95
AkReal32
float AkReal32
32-bit floating point
Definition: AkNumeralTypes.h:46
AkFileHandle
FILE * AkFileHandle
File handle.
Definition: AkTypes.h:77
AkInt32
int32_t AkInt32
Signed 32-bit integer.
Definition: AkNumeralTypes.h:43
AkAsyncIOTransferInfo::pBuffer
void * pBuffer
Buffer for data transfer.
Definition: AkStreamMgrModule.h:121
AkFileOpenCallback
void(* AkFileOpenCallback)(AkAsyncFileOpenData *in_pOpenInfo, AKRESULT in_eResult)
Definition: AkStreamMgrModule.h:133
AkAsyncFileOpenData::pCookie
void * pCookie
Reserved. Pass this unchanged to the callback function. The I/O device uses this cookie to retrieve t...
Definition: AkStreamMgrModule.h:199
AkAsyncFileOpenData::pCustomData
void * pCustomData
Convienience pointer for the IO hook implementer. Useful for additional data used in asynchronous imp...
Definition: AkStreamMgrModule.h:201
AkAsyncFileOpenData::AkAsyncFileOpenData
AkAsyncFileOpenData(const AkAsyncFileOpenData &in_copy)
Definition: AkStreamMgrModule.h:157
AkFileID
AkUInt32 AkFileID
Integer-type file identifier.
Definition: AkTypes.h:159
AkDeviceSettings::uGranularity
AkUInt32 uGranularity
I/O requests granularity (typical bytes/request).
Definition: AkStreamMgrModule.h:66
AK::StreamMgr::IAkLowLevelIOHook::GetDeviceDesc
virtual void GetDeviceDesc(AkDeviceDesc &out_deviceDesc)=0
AK::StreamMgr::PerformIO
AKSOUNDENGINE_API AKRESULT PerformIO()
AkAsyncFileOpenData::pCallback
AkFileOpenCallback pCallback
Callback function used to notify the high-level device when Open is done.
Definition: AkStreamMgrModule.h:198
AkAsyncFileOpenData::SetStreamName
AKRESULT SetStreamName(const AkOSChar *in_pszStreamName)
AK::StreamMgr::IAkLowLevelIOHook::BatchCancel
virtual void BatchCancel(AkUInt32 in_uNumTransfers, BatchIoTransferItem *in_pTransferItems, bool **io_ppbCancelAllTransfersForThisFile)=0
AkPriority
AkInt8 AkPriority
Priority.
Definition: AkTypes.h:149
AK::StreamMgr::IAkFileLocationResolver::GetNextPreferredDevice
virtual AKRESULT GetNextPreferredDevice(AkAsyncFileOpenData &in_FileOpen, AkDeviceID &io_idDevice)
Definition: AkStreamMgrModule.h:436
AK::StreamMgr::CreateDevice
AKSOUNDENGINE_API AKRESULT CreateDevice(const AkDeviceSettings &in_settings, IAkLowLevelIOHook *in_pLowLevelHook, AkDeviceID &out_idDevice)
AK_CALLBACK
#define AK_CALLBACK(_type, _name)
Definition: AkSoundEngineExport.h:87
AK::StreamMgr::IAkLowLevelIOHook::Close
virtual AKRESULT Close(AkFileDesc *in_pFileDesc)=0
AK_NotImplemented
@ AK_NotImplemented
This feature is not implemented.
Definition: AkTypes.h:214
AkFileDesc::uSector
AkUInt64 uSector
Definition: AkStreamMgrModule.h:82
AkFileSystemFlags
File system flags for file descriptors mapping.
Definition: IAkStreamMgr.h:81
AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize
virtual AkUInt32 GetBlockSize(AkFileDesc &in_fileDesc)=0
AkInt64
int64_t AkInt64
Signed 64-bit integer.
Definition: AkNumeralTypes.h:44
AkAsyncFileOpenData::GetStreamName
const AkOSChar * GetStreamName() const
Definition: AkStreamMgrModule.h:196
AkAsyncIOTransferInfo::pCallback
AkIOCallback pCallback
Callback function used to notify the high-level device when the transfer is complete.
Definition: AkStreamMgrModule.h:122
AkUInt64
uint64_t AkUInt64
Unsigned 64-bit integer.
Definition: AkNumeralTypes.h:39
AK::StreamMgr::GetFileLocationResolver
AKSOUNDENGINE_API IAkFileLocationResolver * GetFileLocationResolver()
AK::StreamMgr::IAkLowLevelIOHook::BatchWrite
virtual void BatchWrite(AkUInt32 in_uNumTransfers, BatchIoTransferItem *in_pTransferItems)=0
AK::StreamMgr::Create
AKSOUNDENGINE_API IAkStreamMgr * Create(const AkStreamMgrSettings &in_settings)
AK::StreamMgr::FlushAllCaches
AKSOUNDENGINE_API void FlushAllCaches()
AkOpenMode
AkOpenMode
File open mode.
Definition: IAkStreamMgr.h:72
AkDeviceDesc
Device descriptor.
Definition: IAkStreamMgr.h:162
AK::StreamMgr::GetDefaultDeviceSettings
AKSOUNDENGINE_API void GetDefaultDeviceSettings(AkDeviceSettings &out_settings)
AK::StreamMgr::SetFileLocationResolver
AKSOUNDENGINE_API void SetFileLocationResolver(IAkFileLocationResolver *in_pFileLocationResolver)
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkNumeralTypes.h:38
AkAsyncFileOpenData::pFileDesc
AkFileDesc * pFileDesc
File Descriptor to fill once the Open operation is complete.
Definition: AkStreamMgrModule.h:200
AK::StreamMgr::IAkLowLevelIOHook::BatchOpen
virtual void BatchOpen(AkUInt32 in_uNumFiles, AkAsyncFileOpenData **in_ppItems)=0
AK::StreamMgr::RemoveLanguageChangeObserver
AKSOUNDENGINE_API void RemoveLanguageChangeObserver(void *in_pCookie)
AK::StreamMgr::AddLanguageChangeObserver
AKSOUNDENGINE_API AKRESULT AddLanguageChangeObserver(AkLanguageChangeHandler in_handler, void *in_pCookie)
AkIOTransferInfo::uFilePosition
AkUInt64 uFilePosition
File offset where transfer should begin.
Definition: AkStreamMgrModule.h:94
AK::StreamMgr::IAkFileLocationResolver::~IAkFileLocationResolver
virtual ~IAkFileLocationResolver()
Virtual destructor on interface to avoid warnings.
Definition: AkStreamMgrModule.h:419
AkDeviceSettings::uIOMemorySize
AkUInt32 uIOMemorySize
Size of memory for I/O (for automatic streams). It is passed directly to AK::MemoryMgr::Malign(),...
Definition: AkStreamMgrModule.h:63
AkFileDesc::hFile
AkFileHandle hFile
File handle/identifier.
Definition: AkStreamMgrModule.h:86
AK::StreamMgr::IAkLowLevelIOHook::OutputSearchedPaths
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
AkFileDesc::iFileSize
AkInt64 iFileSize
File size in bytes.
Definition: AkStreamMgrModule.h:81
AK::StreamMgr::GetCurrentLanguage
AKSOUNDENGINE_API const AkOSChar * GetCurrentLanguage()
AkDeviceSettings::threadProperties
AkThreadProperties threadProperties
Scheduler thread properties.
Definition: AkStreamMgrModule.h:67

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell 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