Version
menu_open
link
Wwise SDK 2022.1.4
IAkStreamMgr.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) 2023 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 /// \file
28 /// Defines the API of Audiokinetic's I/O streaming solution.
29 
30 #ifndef _IAK_STREAM_MGR_H_
31 #define _IAK_STREAM_MGR_H_
32 
33 #include <AK/SoundEngine/Common/AkMemoryMgr.h>
34 
35 //-----------------------------------------------------------------------------
36 // Defines.
37 //-----------------------------------------------------------------------------
38 
39 /// \name Profiling string lengths.
40 //@{
41 #define AK_MONITOR_STREAMNAME_MAXLENGTH (64)
42 #define AK_MONITOR_DEVICENAME_MAXLENGTH (16)
43 //@}
44 
45 //-----------------------------------------------------------------------------
46 // Enums.
47 //-----------------------------------------------------------------------------
48 
49 /// Stream status.
50 enum AkStmStatus
51 {
52  AK_StmStatusIdle = 0, ///< The stream is idle
53  AK_StmStatusCompleted = 1, ///< Operation completed / Automatic stream reached end
54  AK_StmStatusPending = 2, ///< Operation pending / The stream is waiting for I/O
55  AK_StmStatusCancelled = 3, ///< Operation cancelled
56  AK_StmStatusError = 4 ///< The low-level I/O reported an error
57 };
58 
59 /// Move method for position change.
60 /// \sa
61 /// - AK::IAkStdStream::SetPosition()
62 /// - AK::IAkAutoStream::SetPosition()
63 enum AkMoveMethod
64 {
65  AK_MoveBegin = 0, ///< Move offset from the start of the stream
66  AK_MoveCurrent = 1, ///< Move offset from the current stream position
67  AK_MoveEnd = 2 ///< Move offset from the end of the stream
68 };
69 
70 /// File open mode.
71 enum AkOpenMode
72 {
73  AK_OpenModeRead = 0, ///< Read-only access
74  AK_OpenModeWrite = 1, ///< Write-only access (opens the file if it already exists)
75  AK_OpenModeWriteOvrwr = 2, ///< Write-only access (deletes the file if it already exists)
76  AK_OpenModeReadWrite = 3 ///< Read and write access
77 };
78 
79 /// File system flags for file descriptors mapping.
80 struct AkFileSystemFlags
81 {
82  AkFileSystemFlags()
83  : uCacheID( AK_INVALID_FILE_ID ), uDirectoryHash( AK_INVALID_UNIQUE_ID ) {}
84 
85  AkFileSystemFlags( AkUInt32 in_uCompanyID, AkUInt32 in_uCodecID, AkUInt32 in_uCustomParamSize, void * in_pCustomParam, bool in_bIsLanguageSpecific, AkFileID in_uCacheID )
86  : uCompanyID( in_uCompanyID )
87  , uCodecID( in_uCodecID )
88  , uCustomParamSize( in_uCustomParamSize )
89  , pCustomParam( in_pCustomParam )
90  , bIsLanguageSpecific( in_bIsLanguageSpecific )
91  , uCacheID( in_uCacheID )
92  , uNumBytesPrefetch( 0 )
93  , uDirectoryHash( AK_INVALID_UNIQUE_ID ) {}
94 
95  AkUInt32 uCompanyID; ///< Company ID (Wwise uses AKCOMPANYID_AUDIOKINETIC, defined in AkTypes.h, for soundbanks and standard streaming files, and AKCOMPANYID_AUDIOKINETIC_EXTERNAL for streaming external sources).
96  AkUInt32 uCodecID; ///< File/codec type ID (defined in AkTypes.h)
97  AkUInt32 uCustomParamSize; ///< Size of the custom parameter
98  void * pCustomParam; ///< Custom parameter
99  bool bIsLanguageSpecific;///< True when the file location depends on language
100  bool bIsAutomaticStream; ///< True when the file is opened to be used as an automatic stream. Note that you don't need to set it.
101  ///< If you pass an AkFileSystemFlags to IAkStreamMgr CreateStd|Auto(), it will be set internally to the correct value.
102  AkFileID uCacheID; ///< Cache ID for caching system used by automatic streams. The user is responsible for guaranteeing unicity of IDs.
103  ///< When set, it supersedes the file ID passed to AK::IAkStreamMgr::CreateAuto() (ID version). Caching is optional and depends on the implementation.
104  AkUInt32 uNumBytesPrefetch; ///< Indicates the number of bytes from the beginning of the file that should be streamed into cache via a caching stream. This field is only relevant when opening caching streams via
105  ///< AK::IAkStreamMgr::PinFileInCache() and AK::SoundEngine::PinEventInStreamCache(). When using AK::SoundEngine::PinEventInStreamCache(),
106  ///< it is initialized to the prefetch size stored in the sound bank, but may be changed by the file location resolver, or set to 0 to cancel caching.
107  AkUInt32 uDirectoryHash; ///< If the implementation uses a hashed directory structure, this is the hash value that should be employed for determining the directory structure
108 };
109 
110 /// Stream information.
111 /// \sa
112 /// - AK::IAkStdStream::GetInfo()
113 /// - AK::IAkAutoStream::GetInfo()
114 struct AkStreamInfo
115 {
116  AkDeviceID deviceID; ///< Device ID
117  const AkOSChar * pszName; ///< User-defined stream name (specified through AK::IAkStdStream::SetStreamName() or AK::IAkAutoStream::SetStreamName())
118  AkUInt64 uSize; ///< Total stream/file size in bytes
119  bool bIsOpen; ///< True when the file is open (implementations may defer file opening)
120 };
121 
122 /// Automatic streams heuristics.
123 struct AkAutoStmHeuristics
124 {
125  AkReal32 fThroughput; ///< Average throughput in bytes/ms
126  AkUInt32 uLoopStart; ///< Set to the start of loop (byte offset from the beginning of the stream) for streams that loop, 0 otherwise
127  AkUInt32 uLoopEnd; ///< Set to the end of loop (byte offset from the beginning of the stream) for streams that loop, 0 otherwise
128  AkUInt8 uMinNumBuffers; ///< Minimum number of buffers if you plan to own more than one buffer at a time, 0 or 1 otherwise
129  ///< \remarks You should always release buffers as fast as possible, therefore this heuristic should be used only when
130  ///< dealing with special contraints, like drivers or hardware that require more than one buffer at a time.\n
131  ///< Also, this is only a heuristic: it does not guarantee that data will be ready when calling AK::IAkAutoStream::GetBuffer().
132  AkPriority priority; ///< The stream priority. it should be between AK_MIN_PRIORITY and AK_MAX_PRIORITY (included).
133 };
134 
135 /// Automatic streams buffer settings/constraints.
136 struct AkAutoStmBufSettings
137 {
138  AkUInt32 uBufferSize; ///< Hard user constraint: When non-zero, forces the I/O buffer to be of size uBufferSize
139  ///< (overriding the device's granularity).
140  ///< Otherwise, the size is determined by the device's granularity.
141  AkUInt32 uMinBufferSize; ///< Soft user constraint: When non-zero, specifies a minimum buffer size
142  ///< \remarks Ignored if uBufferSize is specified.
143  AkUInt32 uBlockSize; ///< Hard user constraint: When non-zero, buffer size will be a multiple of that number, and returned addresses will always be aligned on multiples of this value.
144 };
145 
146 /// \name Profiling structures.
147 //@{
148 
149 #pragma pack(push, 4)
150 
151 /// Device descriptor.
152 struct AkDeviceDesc
153 {
154  AkDeviceID deviceID; ///< Device ID
155  bool bCanWrite; ///< Specifies whether or not the device is writable
156  bool bCanRead; ///< Specifies whether or not the device is readable
157  AkUtf16 szDeviceName[AK_MONITOR_DEVICENAME_MAXLENGTH]; ///< Device name
158  AkUInt32 uStringSize; ///< Device name string's size (number of characters)
159 };
160 
161 /// Device descriptor.
162 struct AkDeviceData
163 {
164  AkDeviceID deviceID; ///< Device ID
165  AkUInt32 uMemSize; ///< IO memory pool size
166  AkUInt32 uMemUsed; ///< IO memory pool used
167  AkUInt32 uAllocs; ///< Cumulative number of allocations
168  AkUInt32 uFrees; ///< Cumulative number of deallocations
169  AkUInt32 uPeakRefdMemUsed; ///< Memory peak since monitoring started
170  AkUInt32 uUnreferencedCachedBytes; ///< IO memory that is cached but is not currently used for active streams.
171  AkUInt32 uGranularity; ///< IO memory pool block size
172  AkUInt32 uNumActiveStreams; ///< Number of streams that have been active in the previous frame
173  AkUInt32 uTotalBytesTransferred; ///< Number of bytes transferred, including cached transfers
174  AkUInt32 uLowLevelBytesTransferred; ///< Number of bytes transferred exclusively via low-level
175  AkReal32 fAvgCacheEfficiency; ///< Total bytes from cache as a percentage of total bytes.
176  AkUInt32 uNumLowLevelRequestsCompleted; ///< Number of low-level transfers that have completed in the previous monitoring frame
177  AkUInt32 uNumLowLevelRequestsCancelled; ///< Number of low-level transfers that were cancelled in the previous monitoring frame
178  AkUInt32 uNumLowLevelRequestsPending; ///< Number of low-level transfers that are currently pending
179  AkUInt32 uCustomParam; ///< Custom number queried from low-level IO.
180  AkUInt32 uCachePinnedBytes; ///< Number of bytes that can be pinned into cache.
181 };
182 
183 /// Stream general information.
184 struct AkStreamRecord
185 {
186  AkUInt32 uStreamID; ///< Unique stream identifier
187  AkDeviceID deviceID; ///< Device ID
188  AkUtf16 szStreamName[AK_MONITOR_STREAMNAME_MAXLENGTH]; ///< Stream name
189  AkUInt32 uStringSize; ///< Stream name string's size (number of characters)
190  AkUInt64 uFileSize; ///< File size
191  AkUInt32 uCustomParamSize; ///< File descriptor's uCustomParamSize
192  AkUInt32 uCustomParam; ///< File descriptor's pCustomParam (on 32 bits)
193  bool bIsAutoStream; ///< True for auto streams
194  bool bIsCachingStream; ///< True for caching streams
195 };
196 
197 /// Stream statistics.
198 struct AkStreamData
199 {
200  AkUInt32 uStreamID; ///< Unique stream identifier
201  // Status (replace)
202  AkUInt32 uPriority; ///< Stream priority
203  AkUInt64 uFilePosition; ///< Current position
204  AkUInt32 uTargetBufferingSize; ///< Total stream buffer size (specific to IAkAutoStream)
205  AkUInt32 uVirtualBufferingSize; ///< Size of available data including requested data (specific to IAkAutoStream)
206  AkUInt32 uBufferedSize; ///< Size of available data (specific to IAkAutoStream)
207  AkUInt32 uNumBytesTransfered; ///< Transfered amount since last query (Accumulate/Reset)
208  AkUInt32 uNumBytesTransferedLowLevel;///< Transfered amount (from low-level IO only) since last query (Accumulate/Reset)
209  AkUInt32 uMemoryReferenced; ///< Amount of streaming memory referenced by this stream
210  AkReal32 fEstimatedThroughput; ///< Estimated throughput heuristic
211  bool bActive; ///< True if this stream has been active (that is, was ready for I/O or had at least one pending I/O transfer, uncached or not) in the previous frame
212 };
213 
214 #pragma pack(pop)
215 
216 //@}
217 
218 namespace AK
219 {
220  /// \name Profiling interfaces.
221  //@{
222 
223  /// Profiling interface of streams.
224  /// \akwarning
225  /// The functions in this interface are not thread-safe, unless stated otherwise.
226  /// \endakwarning
227  class IAkStreamProfile
228  {
229  protected:
230  /// Virtual destructor on interface to avoid warnings.
231  virtual ~IAkStreamProfile(){}
232 
233  public:
234  /// Returns the stream's record (once).
235  /// \sa
236  /// - \ref streamingdevicemanager
237  virtual void GetStreamRecord(
238  AkStreamRecord & out_streamRecord ///< Returned stream record interface
239  ) = 0;
240 
241  /// Returns the stream's statistics (every profile frame).
242  /// \sa
243  /// - \ref streamingdevicemanager
244  virtual void GetStreamData(
245  AkStreamData & out_streamData ///< Returned periodic stream data interface
246  ) = 0;
247 
248  /// Query the stream's "new" flag.
249  /// \return True, until AK::IAkStreamProfile::ClearNew() is called.
250  /// \sa
251  /// - \ref streamingdevicemanager
252  virtual bool IsNew() = 0;
253 
254  /// Resets the stream's "new" flag.
255  /// \sa
256  /// - \ref streamingdevicemanager
257  virtual void ClearNew() = 0;
258  };
259 
260 
261  /// Profiling interface of high-level I/O devices.
262  /// \akwarning
263  /// The functions in this interface are not thread-safe, unless stated otherwise.
264  /// \endakwarning
265  class IAkDeviceProfile
266  {
267  protected:
268  /// Virtual destructor on interface to avoid warnings.
269  virtual ~IAkDeviceProfile(){}
270 
271  public:
272 
273  /// Notify device when monitor sampling starts.
274  virtual void OnProfileStart() = 0;
275 
276  /// Notify device when monitor sampling ends.
277  virtual void OnProfileEnd() = 0;
278 
279  /// Query the device's description (once).
280  /// \sa
281  /// - \ref streamingdevicemanager
282  virtual void GetDesc(
283  AkDeviceDesc & out_deviceDesc ///< Device descriptor.
284  ) = 0;
285 
286  /// Query the device's statistics (at every profiling frame).
287  /// \sa
288  /// - \ref streamingdevicemanager
289  virtual void GetData(
290  AkDeviceData & out_deviceData ///< Device data.
291  ) = 0;
292 
293  /// Query the device's "new" flag.
294  /// \return True, until ClearNew() is called.
295  /// \sa
296  /// - \ref streamingdevicemanager
297  virtual bool IsNew() = 0;
298 
299  /// Resets the device's "new" flag.
300  /// \sa
301  /// - \ref streamingdevicemanager
302  virtual void ClearNew() = 0;
303 
304  /// Get the number of streams currently associated with that device.
305  /// \return The number of streams
306  /// \sa
307  /// - \ref streamingdevicemanager
308  virtual AkUInt32 GetNumStreams() = 0;
309 
310  /// Get a stream profile, for a specified stream index.
311  /// \remarks GetStreamProfile() refers to streams by index, which must honor the call to AK::IAkDeviceProfile::GetNumStreams().
312  /// \sa
313  /// - \ref streamingdevicemanager
314  virtual IAkStreamProfile * GetStreamProfile(
315  AkUInt32 in_uStreamIndex ///< Stream index: [0,numStreams[
316  ) = 0;
317  };
318 
319  /// Profiling interface of the Stream Manager.
320  /// \akwarning
321  /// The functions in this interface are not thread-safe, unless stated otherwise.
322  /// \endakwarning
323  class IAkStreamMgrProfile
324  {
325  protected:
326  /// Virtual destructor on interface to avoid warnings.
327  virtual ~IAkStreamMgrProfile(){}
328 
329  public:
330  /// Start profile monitoring.
331  /// \return AK_Success if successful, AK_Fail otherwise.
332  /// \sa
333  /// - \ref streamingdevicemanager
334  virtual AKRESULT StartMonitoring() = 0;
335 
336  /// Stop profile monitoring.
337  /// \sa
338  /// - \ref streamingdevicemanager
339  virtual void StopMonitoring() = 0;
340 
341  /// Device enumeration.
342  /// \return The number of devices.
343  /// \sa
344  /// - \ref streamingdevicemanager
345  virtual AkUInt32 GetNumDevices() = 0;
346 
347  /// Get a device profile for a specified device index.
348  /// \remarks GetDeviceProfile() refers to devices by index, which must honor the call to AK::IAkStreamMgrProfile::GetNumDevices().
349  /// \remarks The device index is not the same as the device ID (AkDeviceID).
350  /// \sa
351  /// - \ref streamingdevicemanager
352  virtual IAkDeviceProfile * GetDeviceProfile(
353  AkUInt32 in_uDeviceIndex ///< Device index: [0,numDevices[
354  ) = 0;
355  };
356  //@}
357 
358  /// \name High-level streams API.
359  //@{
360 
361  /// Interface of standard streams. Used as a handle to a standard stream. Has methods for
362  /// stream control. Obtained through the Stream Manager's AK::IAkStreamMgr::CreateStd() method.
363  /// \akwarning
364  /// The functions in this interface are not thread-safe, unless stated otherwise.
365  /// \endakwarning
366  class IAkStdStream
367  {
368  protected:
369  /// Virtual destructor on interface to avoid warnings.
370  virtual ~IAkStdStream(){}
371 
372  public:
373  /// \name Stream management and settings.
374  //@{
375  /// Close the stream. The object is destroyed and the interface becomes invalid.
376  /// \sa
377  /// - \ref streamingdevicemanager
378  virtual void Destroy() = 0;
379 
380  /// Get information about a stream.
381  /// \sa
382  /// - \ref streamingdevicemanager
383  virtual void GetInfo(
384  AkStreamInfo & out_info ///< Returned stream info
385  ) = 0;
386 
387  /// Returns a unique cookie for a given stream.
388  /// The default implementation of the Stream Manager returns its file descriptor (see AkStreamMgrModule.h).
389  virtual void * GetFileDescriptor() = 0;
390 
391  /// Give the stream a name (appears in the Wwise Profiler).
392  /// \sa
393  /// - \ref streamingdevicemanager
394  virtual AKRESULT SetStreamName(
395  const AkOSChar * in_pszStreamName ///< Stream name
396  ) = 0;
397 
398  /// Get the I/O block size.
399  /// \remark Queries the low-level I/O, by calling AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize() with the
400  /// stream's file descriptor.
401  /// \return The block size, in bytes.
402  /// \sa
403  /// - \ref streamingdevicemanager
404  virtual AkUInt32 GetBlockSize() = 0;
405  //@}
406 
407  /// \name I/O operations.
408  //@{
409 
410  /// Schedule a read request.
411  /// \warning Use only with a multiple of the block size, queried via AK::IAkStdStream::GetBlockSize().
412  /// \remarks If the call is asynchronous (in_bWait = false), wait until AK::IAkStdStream::GetStatus() stops returning AK_StmStatusPending.
413  /// \return AK_Success if the operation was successfully scheduled (but not necessarily completed)
414  /// \sa
415  /// - \ref streamingdevicemanager
416  virtual AKRESULT Read(
417  void * in_pBuffer, ///< User buffer address
418  AkUInt32 in_uReqSize, ///< Requested read size
419  bool in_bWait, ///< Block until the operation is complete
420  AkPriority in_priority, ///< Heuristic: operation priority
421  AkReal32 in_fDeadline, ///< Heuristic: operation deadline (ms)
422  AkUInt32 & out_uSize ///< The size that was actually read
423  ) = 0;
424 
425  /// Schedule a write request.
426  /// \warning Use only with a multiple of the block size, queried via AK::IAkStdStream::GetBlockSize().
427  /// \remarks If the call is asynchronous (in_bWait = false), wait until GetStatus() stops returning AK_StmStatusPending.
428  /// \return AK_Success if the operation was successfully scheduled
429  /// \sa
430  /// - \ref streamingdevicemanager
431  virtual AKRESULT Write(
432  void * in_pBuffer, ///< User buffer address
433  AkUInt32 in_uReqSize, ///< Requested write size
434  bool in_bWait, ///< Block until the operation is complete
435  AkPriority in_priority, ///< Heuristic: operation priority
436  AkReal32 in_fDeadline, ///< Heuristic: operation deadline (ms)
437  AkUInt32 & out_uSize ///< The size that was actually written
438  ) = 0;
439 
440  /// Get the current stream position.
441  /// \remarks If an operation is pending, there is no guarantee that the position was queried before (or after) the operation was completed.
442  /// \return The current stream position
443  /// \sa
444  /// - \ref streamingdevicemanager
445  virtual AkUInt64 GetPosition(
446  bool * out_pbEndOfStream ///< Returned end-of-stream flag, only for streams opened with AK_OpenModeRead (can pass NULL)
447  ) = 0;
448 
449  /// Set the stream position. Modifies the position for the next read/write operation.
450  /// \warning No operation should be pending.
451  /// \remarks The new position will snap to the lowest block boundary.
452  /// \return AK_Success if the stream position was changed
453  /// \sa
454  /// - \ref streamingdevicemanager
455  virtual AKRESULT SetPosition(
456  AkInt64 in_iMoveOffset, ///< Seek offset
457  AkMoveMethod in_eMoveMethod, ///< Seek method, from the beginning, end, or current file position
458  AkInt64 * out_piRealOffset ///< The actual seek offset may differ from the expected value when the block size is bigger than 1.
459  ///< In that case, the seek offset floors to the sector boundary. Can pass NULL.
460  ) = 0;
461 
462  /// Cancel the current operation.
463  /// \remarks When it returns, the caller is guaranteed that no operation is pending.
464  /// \remarks This method can block the caller for the whole duration of the I/O operation, if the request was already posted.
465  /// \sa
466  /// - \ref streamingdevicemanager
467  virtual void Cancel() = 0;
468 
469  //@}
470 
471  /// \name Access to data and status.
472  //@{
473  /// Get user data (and accessed size).
474  /// \return The address of data provided by user
475  /// \sa
476  /// - \ref streamingdevicemanager
477  virtual void * GetData(
478  AkUInt32 & out_uSize ///< Size actually read or written
479  ) = 0;
480 
481  /// Get the stream's status.
482  /// \return The stream status.
483  /// \sa
484  /// - \ref streamingdevicemanager
485  virtual AkStmStatus GetStatus() = 0;
486 
487  /// Block and wait for a pending read to finish, and return the current status of the stream.
488  /// This will return immediately if the status is not pending.
489  /// \return The stream status.
490  /// \sa
491  /// - \ref streamingdevicemanager
492  virtual AkStmStatus WaitForPendingOperation() = 0;
493 
494  //@}
495  };
496 
497 
498  /// Interface of automatic streams. It is used as a handle to a stream,
499  /// I/O operations are triggered from here.
500  /// Obtained through the Stream Manager's AK::IAkStreamMgr::CreateAuto() method.
501  /// \akwarning
502  /// The functions in this interface are not thread-safe, unless stated otherwise.
503  /// \endakwarning
504  /// \sa
505  /// - \ref streamingdevicemanager
506  class IAkAutoStream
507  {
508  protected:
509  /// Virtual destructor on interface to avoid warnings.
510  virtual ~IAkAutoStream(){}
511 
512  public:
513  /// \name Stream management, settings access, and run-time change.
514  //@{
515  /// Close the stream. The object is destroyed and the interface becomes invalid.
516  /// \sa
517  /// - \ref streamingdevicemanager
518  virtual void Destroy() = 0;
519 
520  /// Get information about the stream.
521  /// \sa
522  /// - \ref streamingdevicemanager
523  virtual void GetInfo(
524  AkStreamInfo & out_info ///< Returned stream info
525  ) = 0;
526 
527  /// Returns a unique cookie for a given stream.
528  /// The default implementation of the Stream Manager returns its file descriptor (see AkStreamMgrModule.h).
529  virtual void * GetFileDescriptor() = 0;
530 
531  /// Get the stream's heuristics.
532  /// \sa
533  /// - \ref streamingdevicemanager
534  virtual void GetHeuristics(
535  AkAutoStmHeuristics & out_heuristics///< Returned stream heuristics
536  ) = 0;
537 
538  /// Run-time change of the stream's heuristics.
539  /// \sa
540  /// - \ref streamingdevicemanager
541  virtual AKRESULT SetHeuristics(
542  const AkAutoStmHeuristics & in_heuristics ///< New stream heuristics
543  ) = 0;
544 
545  /// Run-time change of the stream's minimum buffer size that can be handed out to client
546  /// in GetBuffer() (except the last buffer at the end of file).
547  /// Corresponds to the uMinBufferSize field of the AkAutoStmBufSettings passed to CreateAuto().
548  /// \sa
549  /// - AkAutoStmBufSettings
550  /// - \ref streamingdevicemanager
551  virtual AKRESULT SetMinimalBufferSize(
552  AkUInt32 in_uMinBufferSize ///< Minimum buffer size that can be handed out to client.
553  ) = 0;
554 
555  /// Set the minimum size to buffer ahead in an automated stream.
556  ///
557  /// This function was made available to allow systems that cannot only rely on AkAutoStmHeuristics::fThroughput to predict what will be the best target size of an automatic stream.
558  /// The system will predict the minimum size to buffer and will consider this value as the minimal size to be the target.
559  /// \sa
560  /// - AkAutoStmBufSettings
561  /// - \ref streamingdevicemanager
562  /// - \ref AkAutoStmHeuristics
563  virtual AKRESULT SetMinTargetBufferSize(
564  AkUInt32 in_uMinTargetBufferSize ///< Minimum size to buffer ahead in an automated stream. (in bytes)
565  ) = 0;
566 
567  /// Give the stream a name (appears in the Wwise profiler).
568  /// \sa
569  /// - \ref streamingdevicemanager
570  virtual AKRESULT SetStreamName(
571  const AkOSChar * in_pszStreamName ///< Stream name
572  ) = 0;
573 
574  /// Get the I/O block size.
575  /// \remark Queries the actual low-level I/O device, by calling AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize() with the
576  /// stream's file descriptor.
577  /// \return The block size (in bytes)
578  /// \sa
579  /// - \ref streamingdevicemanager
580  virtual AkUInt32 GetBlockSize() = 0;
581 
582  /// Get the amount of buffering that the stream has.
583  /// The buffering is defined as the number of bytes that the stream has buffered, excluding the number
584  /// of bytes that is currently granted to the user (with GetBuffer()).
585  /// \remark The returned value corresponds to the buffering status at that moment, and does not even
586  /// guarantee that it will not shrink.
587  /// \return
588  /// - AK_DataReady: Some data has been buffered (out_uNumBytesAvailable is greater than 0).
589  /// - AK_NoDataReady: No data is available, and the end of file has not been reached.
590  /// - AK_NoMoreData: Some or no data is available, but the end of file has been reached. The stream will not buffer any more data.
591  /// - AK_Fail: The stream is invalid due to an I/O error.
592  virtual AKRESULT QueryBufferingStatus(
593  AkUInt32 & out_uNumBytesAvailable ///< Number of bytes available in the stream's buffer(s).
594  ) = 0;
595 
596  /// Returns the target buffering size based on the throughput heuristic.
597  /// \return
598  /// Target buffering length expressed in bytes.
599  virtual AkUInt32 GetNominalBuffering() = 0;
600 
601  //@}
602 
603  /// \name Stream operations.
604  //@{
605 
606  /// Start the automatic scheduling.
607  /// \return AK_Success if the automatic scheduling was started successfully
608  /// \sa
609  /// - \ref streamingdevicemanager
610  virtual AKRESULT Start() = 0;
611 
612  /// Stop the automatic scheduling.
613  /// \return AK_Success if the automatic scheduling was stopped successfully.
614  /// \sa
615  /// - \ref streamingdevicemanager
616  virtual AKRESULT Stop() = 0;
617 
618  /// Get the stream's position.
619  /// \remarks The stream position is the position seen by the user, not the position of the file
620  /// already streamed into the Stream Manager's memory. The stream position is updated when buffers
621  /// are released, using AK::IAkAutoStream::ReleaseBuffer().
622  /// \return The file position in bytes of the beginning of the first buffer owned by the user.
623  /// If the user does not own a buffer, it returns the position of the beginning of the buffer that
624  /// would be returned from a call to AK::IAkAutoStream::GetBuffer().
625  /// \sa
626  /// - \ref streamingdevicemanager
627  virtual AkUInt64 GetPosition(
628  bool * out_pbEndOfStream ///< Returned end-of-stream flag (can pass NULL)
629  ) = 0;
630 
631  /// Set the stream's position.
632  /// The next call to AK::IAkAutoStream::GetBuffer() will grant data that corresponds to the position specified here.
633  /// \remarks Data already streamed into the Stream Manager's memory might be flushed.
634  /// \remarks The new position will round down to the low-level I/O block size.
635  /// \return AK_Success if the resulting position is valid
636  /// \sa
637  /// - \ref streamingdevicemanager
638  virtual AKRESULT SetPosition(
639  AkInt64 in_iMoveOffset, ///< Seek offset
640  AkMoveMethod in_eMoveMethod, ///< Seek method, from the beginning, end or current file position
641  AkInt64 * out_piRealOffset ///< The actual seek offset may differ from the expected value when the low-level's block size is greater than 1.
642  ///< In that case, the real absolute position rounds down to the block boundary. Can pass NULL.
643  ) = 0;
644 
645  //@}
646 
647 
648  /// \name Data/status access.
649  //@{
650 
651  /// Get data from the Stream Manager buffers.
652  /// \remarks Grants a buffer if data is available. Each successful call to this method returns a new
653  /// buffer of data, at the current stream position.
654  /// Buffers should be released as soon as they are not needed, using AK::IAkAutoStream::ReleaseBuffer().
655  /// \aknote AK::IAkAutoStream::ReleaseBuffer() does not take any argument, because it releases buffers in order. \endaknote
656  /// \return
657  /// - AK_DataReady : the buffer was granted
658  /// - AK_NoDataReady : the buffer is not granted yet (never happens when called with in_bWait flag)
659  /// - AK_NoMoreData : the buffer was granted but reached end of file (next call will return with size 0)
660  /// - AK_Fail : there was an I/O error
661  /// \sa
662  /// - \ref streamingdevicemanager
663  virtual AKRESULT GetBuffer(
664  void *& out_pBuffer, ///< Returned address of granted data space
665  AkUInt32 & out_uSize, ///< Returned size of granted data space
666  bool in_bWait ///< Block until data is ready
667  ) = 0;
668 
669  /// Release buffer granted through GetBuffer(). Buffers are released in order.
670  /// \return AK_Success if a valid buffer was released, AK_Fail if the user did not own any buffer.
671  /// \note To implementers: Clients like the sound engine may release buffers until this function returns AK_Fail.
672  /// Failing to release a buffer should not be considered as a fatal error.
673  /// \sa
674  /// - \ref streamingdevicemanager
675  virtual AKRESULT ReleaseBuffer() = 0;
676  //@}
677  };
678 
679  //@}
680 
681 
682  /// Interface of the Stream Manager.
683  /// \akwarning
684  /// The functions in this interface are not thread-safe, unless stated otherwise.
685  /// \endakwarning
686  class IAkStreamMgr
687  {
688  protected:
689  /// Virtual destructor on interface to avoid warnings.
690  virtual ~IAkStreamMgr(){}
691 
692  public:
693  /// Global access to singleton.
694  /// \return The interface of the global Stream Manager
695  /// \sa
696  /// - \ref streamingdevicemanager
697  inline static IAkStreamMgr * Get()
698  {
699  return m_pStreamMgr;
700  }
701 
702  /// Destroy the Stream Manager.
703  /// \sa
704  /// - \ref streamingdevicemanager
705  virtual void Destroy() = 0;
706 
707 
708  /// \name Profiling.
709  //@{
710  /// Get the profiling interface.
711  /// \return The interface of the Stream Manager profiler
712  virtual IAkStreamMgrProfile * GetStreamMgrProfile() = 0;
713  //@}
714 
715 
716  /// \name Stream creation interface.
717  //@{
718 
719  // Standard stream creation methods.
720 
721  /// Create a standard stream (string overload).
722  /// \return AK_Success if the stream was created successfully
723  /// \remarks The string overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
724  /// \sa
725  /// - \ref streamingdevicemanager
726  virtual AKRESULT CreateStd(
727  const AkOSChar* in_pszFileName, ///< Application-defined string (title only, or full path, or code...)
728  AkFileSystemFlags * in_pFSFlags, ///< Special file system flags. Can pass NULL
729  AkOpenMode in_eOpenMode, ///< Open mode (read, write, ...)
730  IAkStdStream *& out_pStream, ///< Returned interface to a standard stream. If the function does not return AK_Success, this pointer is left untouched.
731  bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
732  ) = 0;
733 
734  /// Create a standard stream (ID overload).
735  /// \return AK_Success if the stream was created successfully
736  /// \remarks The ID overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
737  /// \sa
738  /// - \ref streamingdevicemanager
739  virtual AKRESULT CreateStd(
740  AkFileID in_fileID, ///< Application-defined ID
741  AkFileSystemFlags * in_pFSFlags, ///< Special file system flags (can pass NULL)
742  AkOpenMode in_eOpenMode, ///< Open mode (read, write, ...)
743  IAkStdStream *& out_pStream, ///< Returned interface to a standard stream. If the function does not return AK_Success, this pointer is left untouched.
744  bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
745  ) = 0;
746 
747 
748  // Automatic stream create methods.
749 
750  /// Create an automatic stream (string overload).
751  /// \return AK_Success if the stream was created successfully
752  /// \remarks The stream needs to be started explicitly with AK::IAkAutoStream::Start().
753  /// \remarks The string overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
754  /// \sa
755  /// - \ref streamingdevicemanager
756  virtual AKRESULT CreateAuto(
757  const AkOSChar* in_pszFileName, ///< Application-defined string (title only, or full path, or code...)
758  AkFileSystemFlags * in_pFSFlags, ///< Special file system flags (can pass NULL)
759  const AkAutoStmHeuristics & in_heuristics, ///< Streaming heuristics
760  AkAutoStmBufSettings * in_pBufferSettings, ///< Stream buffer settings (it is recommended to pass NULL in order to use the default settings)
761  IAkAutoStream *& out_pStream, ///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched.
762  bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
763  ) = 0;
764 
765  /// Create an automatic stream (ID overload).
766  /// \return AK_Success if the stream was created successfully
767  /// \remarks The stream needs to be started explicitly with IAkAutoStream::Start().
768  /// \remarks The ID overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
769  /// \sa
770  /// - \ref streamingdevicemanager
771  virtual AKRESULT CreateAuto(
772  AkFileID in_fileID, ///< Application-defined ID
773  AkFileSystemFlags * in_pFSFlags, ///< Special file system flags (can pass NULL)
774  const AkAutoStmHeuristics & in_heuristics, ///< Streaming heuristics
775  AkAutoStmBufSettings * in_pBufferSettings, ///< Stream buffer settings (it is recommended to pass NULL to use the default settings)
776  IAkAutoStream *& out_pStream, ///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched.
777  bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
778  ) = 0;
779 
780  /// Create an automatic stream (in-memory buffer overload).
781  ///
782  /// This overload differs largely from CreateAuto() implementations, which are file based.
783  /// This version is provided with a memory space and the resulting automatic stream will simply
784  /// return the memory space in a similar fashion, but without the need to perform any actual file operations.
785  ///
786  /// If you are in the process of implementing your own IAkStreamMgr object,
787  /// consider using the initial implementation from `\\SDK\\source\\StreamManager\\Common\\AkStreamMgr.cpp`.
788  ///
789  /// \return AK_Success if the stream was created successfully
790  /// \remarks The stream needs to be started explicitly with IAkAutoStream::Start().
791  /// \sa
792  /// - \ref streamingdevicemanager
793  virtual AKRESULT CreateAuto(
794  void * in_pBuffer, ///< Pointer to the memory area containing stream data
795  AkUInt64 in_uSize, ///< Size of the memory area containing stream data
796  const AkAutoStmHeuristics & in_heuristics, ///< Streaming heuristics
797  IAkAutoStream *& out_pStream ///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched.
798  ) = 0;
799 
800  /// Start streaming the first "in_pFSFlags->uNumBytesPrefetch" bytes of the file with id "in_fileID" into cache. The stream will be scheduled only after
801  /// all regular streams (not file caching streams) are serviced. The file will stay cached until either the UnpinFileInCache is called,
802  /// or the limit as set by uMaxCachePinnedBytes is reached and another higher priority file (in_uPriority) needs the space.
803  /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API.
804  /// Using PinFileInCache() directly does not allow users to take advantage of sound bank data. The file and the number of bytes they wish to cache must be explicitly specified.
805  ///
806  /// \sa
807  /// - \ref streamingdevicemanager
808  /// - AK::SoundEngine::PinEventInStreamCache
809  /// - AK::SoundEngine::UnpinEventInStreamCache
810  /// - AkFileSystemFlags
811  virtual AKRESULT PinFileInCache(
812  AkFileID in_fileID, ///< Application-defined ID
813  AkFileSystemFlags * in_pFSFlags, ///< Special file system flags (can NOT pass NULL)
814  AkPriority in_uPriority ///< Stream caching priority. Note: Caching requests only get serviced after all regular streaming requests.
815  ) = 0;
816 
817  /// Un-pin a file that has been previouly pinned into cache. This function must be called once for every call to PinFileInCache() with the same file id.
818  /// The file may still remain in stream cache after this is called, until the memory is reused by the streaming memory manager in accordance with to its
819  /// cache management algorithm.
820  /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API.
821  /// Using UnpinFileInCache() directly does not allow users to take advantage of sound bank data. The file must be explicitly specified.
822  /// \sa
823  /// - \ref streamingdevicemanager
824  /// - AK::SoundEngine::PinEventInStreamCache
825  /// - AK::SoundEngine::UnpinEventInStreamCache
826  virtual AKRESULT UnpinFileInCache(
827  AkFileID in_fileID, ///< Application-defined ID
828  AkPriority in_uPriority ///< Priority of stream that you are unpinning
829  ) = 0;
830 
831  /// Update the priority of the caching stream. Higher priority streams will be serviced before lower priority caching streams, and will be more likely to stay in
832  /// memory if the cache pin limit as set by "uMaxCachePinnedBytes" is reached.
833  /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API.
834  /// Using UpdateCachingPriority() directly does not allow users to take advantage of sound bank data. The file must be explicitly specified.
835  /// \sa
836  /// - \ref streamingdevicemanager
837  /// - AK::SoundEngine::PinEventInStreamCache
838  /// - AK::SoundEngine::UnpinEventInStreamCache
839  virtual AKRESULT UpdateCachingPriority(
840  AkFileID in_fileID, ///< Application-defined ID
841  AkPriority in_uPriority, ///< Priority
842  AkPriority in_uOldPriority ///< Old priority
843  ) = 0;
844 
845  /// Return information about a file that has been pinned into cache.
846  /// Retrieves the percentage of the requested buffer size that has been streamed in and stored into stream cache, and whether
847  /// the cache pinned memory limit is preventing this buffer from filling.
848  virtual AKRESULT GetBufferStatusForPinnedFile(
849  AkFileID in_fileID, ///< Application-defined ID
850  AkReal32& out_fPercentBuffered, ///< Percentage of buffer full (out of 100)
851  bool& out_bCacheFull ///< Set to true if the rest of the buffer can not fit into the cache-pinned memory limit.
852  ) = 0;
853 
854  /// Make a memory stream point to a new area in memory, otherwise keeping the exact same state.
855  virtual AKRESULT RelocateMemoryStream(
856  IAkAutoStream * in_pStream, ///< The stream to relocate. Must be a stream created with the memory overload of CreateAutoStm.
857  AkUInt8 * in_pNewStart ///< The new area in memory to point to
858  ) = 0;
859 
860  //@}
861 
862  protected:
863  /// Definition of the global pointer to the interface of the Stream Manager singleton.
864  /// \sa
865  /// - \ref streamingdevicemanager
866  static AKSOUNDENGINE_API IAkStreamMgr * m_pStreamMgr;
867  };
868 
869 }
870 #endif //_IAK_STREAM_MGR_H_
AkFileSystemFlags::uNumBytesPrefetch
AkUInt32 uNumBytesPrefetch
Definition: IAkStreamMgr.h:104
AkStreamInfo::bIsOpen
bool bIsOpen
True when the file is open (implementations may defer file opening)
Definition: IAkStreamMgr.h:119
AkDeviceData::uCachePinnedBytes
AkUInt32 uCachePinnedBytes
Number of bytes that can be pinned into cache.
Definition: IAkStreamMgr.h:180
AkAutoStmHeuristics::uLoopStart
AkUInt32 uLoopStart
Set to the start of loop (byte offset from the beginning of the stream) for streams that loop,...
Definition: IAkStreamMgr.h:126
AK::IAkStreamMgr::Get
static IAkStreamMgr * Get()
Definition: IAkStreamMgr.h:697
AkStreamData::uBufferedSize
AkUInt32 uBufferedSize
Size of available data (specific to IAkAutoStream)
Definition: IAkStreamMgr.h:206
AK::IAkStdStream::GetData
virtual void * GetData(AkUInt32 &out_uSize)=0
AkFileSystemFlags::uDirectoryHash
AkUInt32 uDirectoryHash
If the implementation uses a hashed directory structure, this is the hash value that should be employ...
Definition: IAkStreamMgr.h:107
AK::IAkStreamMgr::GetStreamMgrProfile
virtual IAkStreamMgrProfile * GetStreamMgrProfile()=0
AK
Audiokinetic namespace.
Definition: AkWwiseSDKVersion.cs:31
AK_MONITOR_DEVICENAME_MAXLENGTH
#define AK_MONITOR_DEVICENAME_MAXLENGTH
Definition: IAkStreamMgr.h:42
AkStreamInfo::deviceID
AkDeviceID deviceID
Device ID.
Definition: IAkStreamMgr.h:116
AK::IAkStreamProfile::IsNew
virtual bool IsNew()=0
AkStreamRecord::uFileSize
AkUInt64 uFileSize
File size.
Definition: IAkStreamMgr.h:190
AK::IAkAutoStream::SetMinimalBufferSize
virtual AKRESULT SetMinimalBufferSize(AkUInt32 in_uMinBufferSize)=0
AK::IAkAutoStream::GetPosition
virtual AkUInt64 GetPosition(bool *out_pbEndOfStream)=0
AkDeviceDesc::bCanRead
bool bCanRead
Specifies whether or not the device is readable.
Definition: IAkStreamMgr.h:156
AkAutoStmBufSettings
Automatic streams buffer settings/constraints.
Definition: IAkStreamMgr.h:137
AkStreamData::uPriority
AkUInt32 uPriority
Stream priority.
Definition: IAkStreamMgr.h:202
AK::IAkStdStream::GetFileDescriptor
virtual void * GetFileDescriptor()=0
AK::IAkStreamMgrProfile::GetDeviceProfile
virtual IAkDeviceProfile * GetDeviceProfile(AkUInt32 in_uDeviceIndex)=0
AkStreamData::uVirtualBufferingSize
AkUInt32 uVirtualBufferingSize
Size of available data including requested data (specific to IAkAutoStream)
Definition: IAkStreamMgr.h:205
AK::IAkAutoStream::ReleaseBuffer
virtual AKRESULT ReleaseBuffer()=0
AkAutoStmHeuristics::uLoopEnd
AkUInt32 uLoopEnd
Set to the end of loop (byte offset from the beginning of the stream) for streams that loop,...
Definition: IAkStreamMgr.h:127
AkDeviceData::uPeakRefdMemUsed
AkUInt32 uPeakRefdMemUsed
Memory peak since monitoring started.
Definition: IAkStreamMgr.h:169
AK::IAkStreamMgr::~IAkStreamMgr
virtual ~IAkStreamMgr()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:690
AK_OpenModeWriteOvrwr
@ AK_OpenModeWriteOvrwr
Write-only access (deletes the file if it already exists)
Definition: IAkStreamMgr.h:75
AK::IAkAutoStream::GetInfo
virtual void GetInfo(AkStreamInfo &out_info)=0
AK::IAkStdStream::GetBlockSize
virtual AkUInt32 GetBlockSize()=0
AK::IAkStdStream::SetPosition
virtual AKRESULT SetPosition(AkInt64 in_iMoveOffset, AkMoveMethod in_eMoveMethod, AkInt64 *out_piRealOffset)=0
AKRESULT
AKRESULT
Standard function call result.
Definition: AkTypes.h:193
AkDeviceID
AkUInt32 AkDeviceID
I/O device ID.
Definition: AkTypes.h:140
AK::IAkDeviceProfile::GetNumStreams
virtual AkUInt32 GetNumStreams()=0
AK_OpenModeReadWrite
@ AK_OpenModeReadWrite
Read and write access.
Definition: IAkStreamMgr.h:76
AkStreamData::uNumBytesTransferedLowLevel
AkUInt32 uNumBytesTransferedLowLevel
Transfered amount (from low-level IO only) since last query (Accumulate/Reset)
Definition: IAkStreamMgr.h:208
AK::IAkStreamProfile::GetStreamData
virtual void GetStreamData(AkStreamData &out_streamData)=0
AK_OpenModeRead
@ AK_OpenModeRead
Read-only access.
Definition: IAkStreamMgr.h:73
AkAutoStmBufSettings::uBlockSize
AkUInt32 uBlockSize
Hard user constraint: When non-zero, buffer size will be a multiple of that number,...
Definition: IAkStreamMgr.h:143
AK::IAkAutoStream::Stop
virtual AKRESULT Stop()=0
AkStreamRecord::bIsAutoStream
bool bIsAutoStream
True for auto streams.
Definition: IAkStreamMgr.h:193
AkAutoStmBufSettings::uMinBufferSize
AkUInt32 uMinBufferSize
Definition: IAkStreamMgr.h:141
AkAutoStmBufSettings::uBufferSize
AkUInt32 uBufferSize
Definition: IAkStreamMgr.h:138
AkDeviceData::uLowLevelBytesTransferred
AkUInt32 uLowLevelBytesTransferred
Number of bytes transferred exclusively via low-level.
Definition: IAkStreamMgr.h:174
AK::IAkDeviceProfile::OnProfileEnd
virtual void OnProfileEnd()=0
Notify device when monitor sampling ends.
AK::IAkAutoStream::SetMinTargetBufferSize
virtual AKRESULT SetMinTargetBufferSize(AkUInt32 in_uMinTargetBufferSize)=0
AkOSChar
char AkOSChar
Generic character string.
Definition: AkTypes.h:60
AkUInt8
uint8_t AkUInt8
Unsigned 8-bit integer.
Definition: AkNumeralTypes.h:36
AK::IAkAutoStream::GetNominalBuffering
virtual AkUInt32 GetNominalBuffering()=0
AK_MoveEnd
@ AK_MoveEnd
Move offset from the end of the stream.
Definition: IAkStreamMgr.h:67
AK::IAkAutoStream::GetBlockSize
virtual AkUInt32 GetBlockSize()=0
AK::IAkStdStream::GetStatus
virtual AkStmStatus GetStatus()=0
AK::IAkStdStream::Read
virtual AKRESULT Read(void *in_pBuffer, AkUInt32 in_uReqSize, bool in_bWait, AkPriority in_priority, AkReal32 in_fDeadline, AkUInt32 &out_uSize)=0
AK_MoveBegin
@ AK_MoveBegin
Move offset from the start of the stream.
Definition: IAkStreamMgr.h:65
AK::IAkStreamMgr::CreateAuto
virtual AKRESULT CreateAuto(AkFileID in_fileID, AkFileSystemFlags *in_pFSFlags, const AkAutoStmHeuristics &in_heuristics, AkAutoStmBufSettings *in_pBufferSettings, IAkAutoStream *&out_pStream, bool in_bSyncOpen)=0
AkReal32
float AkReal32
32-bit floating point
Definition: AkNumeralTypes.h:46
AkStreamData::uStreamID
AkUInt32 uStreamID
Unique stream identifier.
Definition: IAkStreamMgr.h:200
AK::IAkDeviceProfile::OnProfileStart
virtual void OnProfileStart()=0
Notify device when monitor sampling starts.
AkStreamData
Stream statistics.
Definition: IAkStreamMgr.h:199
AkFileSystemFlags::uCompanyID
AkUInt32 uCompanyID
Company ID (Wwise uses AKCOMPANYID_AUDIOKINETIC, defined in AkTypes.h, for soundbanks and standard st...
Definition: IAkStreamMgr.h:95
AkDeviceDesc::uStringSize
AkUInt32 uStringSize
Device name string's size (number of characters)
Definition: IAkStreamMgr.h:158
AkUtf16
AkUInt16 AkUtf16
Definition: AkTypes.h:61
AK_StmStatusIdle
@ AK_StmStatusIdle
The stream is idle.
Definition: IAkStreamMgr.h:52
AkFileID
AkUInt32 AkFileID
Integer-type file identifier.
Definition: AkTypes.h:139
AK::IAkAutoStream::SetStreamName
virtual AKRESULT SetStreamName(const AkOSChar *in_pszStreamName)=0
AK::IAkDeviceProfile::GetData
virtual void GetData(AkDeviceData &out_deviceData)=0
AK::IAkStreamProfile::ClearNew
virtual void ClearNew()=0
AkDeviceData
Device descriptor.
Definition: IAkStreamMgr.h:163
AK::IAkStreamMgrProfile::~IAkStreamMgrProfile
virtual ~IAkStreamMgrProfile()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:327
AK::IAkStreamMgrProfile::StopMonitoring
virtual void StopMonitoring()=0
AK::IAkAutoStream::SetHeuristics
virtual AKRESULT SetHeuristics(const AkAutoStmHeuristics &in_heuristics)=0
AKSOUNDENGINE_API
#define AKSOUNDENGINE_API
Definition: AkSoundEngineExport.h:58
AkFileSystemFlags::bIsAutomaticStream
bool bIsAutomaticStream
Definition: IAkStreamMgr.h:100
AkStreamData::uTargetBufferingSize
AkUInt32 uTargetBufferingSize
Total stream buffer size (specific to IAkAutoStream)
Definition: IAkStreamMgr.h:204
AkAutoStmHeuristics::fThroughput
AkReal32 fThroughput
Average throughput in bytes/ms.
Definition: IAkStreamMgr.h:125
AK::IAkAutoStream::SetPosition
virtual AKRESULT SetPosition(AkInt64 in_iMoveOffset, AkMoveMethod in_eMoveMethod, AkInt64 *out_piRealOffset)=0
AK::IAkStdStream::SetStreamName
virtual AKRESULT SetStreamName(const AkOSChar *in_pszStreamName)=0
AkDeviceData::uGranularity
AkUInt32 uGranularity
IO memory pool block size.
Definition: IAkStreamMgr.h:171
AkDeviceData::uFrees
AkUInt32 uFrees
Cumulative number of deallocations.
Definition: IAkStreamMgr.h:168
AK::IAkStdStream::WaitForPendingOperation
virtual AkStmStatus WaitForPendingOperation()=0
AkDeviceData::uNumLowLevelRequestsCancelled
AkUInt32 uNumLowLevelRequestsCancelled
Number of low-level transfers that were cancelled in the previous monitoring frame.
Definition: IAkStreamMgr.h:177
AkFileSystemFlags::bIsLanguageSpecific
bool bIsLanguageSpecific
True when the file location depends on language.
Definition: IAkStreamMgr.h:99
AK::IAkStreamMgr::CreateAuto
virtual AKRESULT CreateAuto(void *in_pBuffer, AkUInt64 in_uSize, const AkAutoStmHeuristics &in_heuristics, IAkAutoStream *&out_pStream)=0
AK::IAkStreamMgr::CreateAuto
virtual AKRESULT CreateAuto(const AkOSChar *in_pszFileName, AkFileSystemFlags *in_pFSFlags, const AkAutoStmHeuristics &in_heuristics, AkAutoStmBufSettings *in_pBufferSettings, IAkAutoStream *&out_pStream, bool in_bSyncOpen)=0
AkStreamRecord::uCustomParamSize
AkUInt32 uCustomParamSize
File descriptor's uCustomParamSize.
Definition: IAkStreamMgr.h:191
AkStreamData::bActive
bool bActive
True if this stream has been active (that is, was ready for I/O or had at least one pending I/O trans...
Definition: IAkStreamMgr.h:211
AkDeviceData::uMemUsed
AkUInt32 uMemUsed
IO memory pool used.
Definition: IAkStreamMgr.h:166
AK_MoveCurrent
@ AK_MoveCurrent
Move offset from the current stream position.
Definition: IAkStreamMgr.h:66
AK::IAkStreamMgr::Destroy
virtual void Destroy()=0
AkStreamRecord::uStreamID
AkUInt32 uStreamID
Unique stream identifier.
Definition: IAkStreamMgr.h:186
AK_StmStatusPending
@ AK_StmStatusPending
Operation pending / The stream is waiting for I/O.
Definition: IAkStreamMgr.h:54
AK::IAkDeviceProfile::~IAkDeviceProfile
virtual ~IAkDeviceProfile()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:269
AkStreamRecord
Stream general information.
Definition: IAkStreamMgr.h:185
AK::IAkStreamMgr::RelocateMemoryStream
virtual AKRESULT RelocateMemoryStream(IAkAutoStream *in_pStream, AkUInt8 *in_pNewStart)=0
Make a memory stream point to a new area in memory, otherwise keeping the exact same state.
AkPriority
AkInt8 AkPriority
Priority.
Definition: AkTypes.h:129
AK::IAkStreamMgrProfile::StartMonitoring
virtual AKRESULT StartMonitoring()=0
AkDeviceDesc::deviceID
AkDeviceID deviceID
Device ID.
Definition: IAkStreamMgr.h:154
AkDeviceData::uNumActiveStreams
AkUInt32 uNumActiveStreams
Number of streams that have been active in the previous frame.
Definition: IAkStreamMgr.h:172
AkStreamRecord::uCustomParam
AkUInt32 uCustomParam
File descriptor's pCustomParam (on 32 bits)
Definition: IAkStreamMgr.h:192
AK::IAkAutoStream::QueryBufferingStatus
virtual AKRESULT QueryBufferingStatus(AkUInt32 &out_uNumBytesAvailable)=0
AkStreamInfo::pszName
const AkOSChar * pszName
User-defined stream name (specified through AK::IAkStdStream::SetStreamName() or AK::IAkAutoStream::S...
Definition: IAkStreamMgr.h:117
AkDeviceData::uCustomParam
AkUInt32 uCustomParam
Custom number queried from low-level IO.
Definition: IAkStreamMgr.h:179
AK::IAkStdStream::~IAkStdStream
virtual ~IAkStdStream()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:370
AkDeviceData::uTotalBytesTransferred
AkUInt32 uTotalBytesTransferred
Number of bytes transferred, including cached transfers.
Definition: IAkStreamMgr.h:173
AK::IAkStdStream::GetInfo
virtual void GetInfo(AkStreamInfo &out_info)=0
AK::IAkStreamMgr::PinFileInCache
virtual AKRESULT PinFileInCache(AkFileID in_fileID, AkFileSystemFlags *in_pFSFlags, AkPriority in_uPriority)=0
AkDeviceData::uUnreferencedCachedBytes
AkUInt32 uUnreferencedCachedBytes
IO memory that is cached but is not currently used for active streams.
Definition: IAkStreamMgr.h:170
AK::IAkStreamMgr::CreateStd
virtual AKRESULT CreateStd(const AkOSChar *in_pszFileName, AkFileSystemFlags *in_pFSFlags, AkOpenMode in_eOpenMode, IAkStdStream *&out_pStream, bool in_bSyncOpen)=0
AkFileSystemFlags::AkFileSystemFlags
AkFileSystemFlags(AkUInt32 in_uCompanyID, AkUInt32 in_uCodecID, AkUInt32 in_uCustomParamSize, void *in_pCustomParam, bool in_bIsLanguageSpecific, AkFileID in_uCacheID)
Definition: IAkStreamMgr.h:85
AkStreamRecord::deviceID
AkDeviceID deviceID
Device ID.
Definition: IAkStreamMgr.h:187
AK::IAkStdStream::Destroy
virtual void Destroy()=0
AK::IAkDeviceProfile::GetStreamProfile
virtual IAkStreamProfile * GetStreamProfile(AkUInt32 in_uStreamIndex)=0
AK::IAkAutoStream::GetBuffer
virtual AKRESULT GetBuffer(void *&out_pBuffer, AkUInt32 &out_uSize, bool in_bWait)=0
AkStreamData::fEstimatedThroughput
AkReal32 fEstimatedThroughput
Estimated throughput heuristic.
Definition: IAkStreamMgr.h:210
AK::IAkAutoStream::GetHeuristics
virtual void GetHeuristics(AkAutoStmHeuristics &out_heuristics)=0
AkDeviceData::uAllocs
AkUInt32 uAllocs
Cumulative number of allocations.
Definition: IAkStreamMgr.h:167
AK::IAkStreamMgr::CreateStd
virtual AKRESULT CreateStd(AkFileID in_fileID, AkFileSystemFlags *in_pFSFlags, AkOpenMode in_eOpenMode, IAkStdStream *&out_pStream, bool in_bSyncOpen)=0
AkFileSystemFlags
File system flags for file descriptors mapping.
Definition: IAkStreamMgr.h:81
AkMoveMethod
AkMoveMethod
Definition: IAkStreamMgr.h:64
AK_INVALID_UNIQUE_ID
static const AkUniqueID AK_INVALID_UNIQUE_ID
Invalid unique 32-bit ID.
Definition: AkTypes.h:157
AkDeviceData::uMemSize
AkUInt32 uMemSize
IO memory pool size.
Definition: IAkStreamMgr.h:165
AkDeviceData::uNumLowLevelRequestsPending
AkUInt32 uNumLowLevelRequestsPending
Number of low-level transfers that are currently pending.
Definition: IAkStreamMgr.h:178
AkInt64
int64_t AkInt64
Signed 64-bit integer.
Definition: AkNumeralTypes.h:44
AkFileSystemFlags::uCacheID
AkFileID uCacheID
Definition: IAkStreamMgr.h:102
AK_OpenModeWrite
@ AK_OpenModeWrite
Write-only access (opens the file if it already exists)
Definition: IAkStreamMgr.h:74
AkUInt64
uint64_t AkUInt64
Unsigned 64-bit integer.
Definition: AkNumeralTypes.h:39
AK_StmStatusCompleted
@ AK_StmStatusCompleted
Operation completed / Automatic stream reached end.
Definition: IAkStreamMgr.h:53
AkStreamData::uNumBytesTransfered
AkUInt32 uNumBytesTransfered
Transfered amount since last query (Accumulate/Reset)
Definition: IAkStreamMgr.h:207
AK::IAkDeviceProfile::GetDesc
virtual void GetDesc(AkDeviceDesc &out_deviceDesc)=0
AkStmStatus
AkStmStatus
Stream status.
Definition: IAkStreamMgr.h:51
AkDeviceDesc::bCanWrite
bool bCanWrite
Specifies whether or not the device is writable.
Definition: IAkStreamMgr.h:155
AkOpenMode
AkOpenMode
File open mode.
Definition: IAkStreamMgr.h:72
AkDeviceDesc
Device descriptor.
Definition: IAkStreamMgr.h:153
AkDeviceData::uNumLowLevelRequestsCompleted
AkUInt32 uNumLowLevelRequestsCompleted
Number of low-level transfers that have completed in the previous monitoring frame.
Definition: IAkStreamMgr.h:176
AkStreamInfo::uSize
AkUInt64 uSize
Total stream/file size in bytes.
Definition: IAkStreamMgr.h:118
AK::IAkAutoStream::~IAkAutoStream
virtual ~IAkAutoStream()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:510
AK::IAkAutoStream::Start
virtual AKRESULT Start()=0
AkDeviceData::fAvgCacheEfficiency
AkReal32 fAvgCacheEfficiency
Total bytes from cache as a percentage of total bytes.
Definition: IAkStreamMgr.h:175
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkNumeralTypes.h:38
AK_INVALID_FILE_ID
static const AkFileID AK_INVALID_FILE_ID
Invalid file ID.
Definition: AkTypes.h:164
AkDeviceData::deviceID
AkDeviceID deviceID
Device ID.
Definition: IAkStreamMgr.h:164
AK::IAkStreamProfile::~IAkStreamProfile
virtual ~IAkStreamProfile()
Virtual destructor on interface to avoid warnings.
Definition: IAkStreamMgr.h:231
AK_StmStatusError
@ AK_StmStatusError
The low-level I/O reported an error.
Definition: IAkStreamMgr.h:56
AkStreamRecord::szStreamName
AkUtf16 szStreamName[AK_MONITOR_STREAMNAME_MAXLENGTH]
Stream name.
Definition: IAkStreamMgr.h:188
AK::IAkAutoStream::Destroy
virtual void Destroy()=0
AkStreamRecord::uStringSize
AkUInt32 uStringSize
Stream name string's size (number of characters)
Definition: IAkStreamMgr.h:189
AK::IAkStreamMgrProfile::GetNumDevices
virtual AkUInt32 GetNumDevices()=0
AkFileSystemFlags::uCustomParamSize
AkUInt32 uCustomParamSize
Size of the custom parameter.
Definition: IAkStreamMgr.h:97
AkAutoStmHeuristics::priority
AkPriority priority
The stream priority. it should be between AK_MIN_PRIORITY and AK_MAX_PRIORITY (included).
Definition: IAkStreamMgr.h:132
AK::IAkStdStream::Cancel
virtual void Cancel()=0
AkStreamData::uMemoryReferenced
AkUInt32 uMemoryReferenced
Amount of streaming memory referenced by this stream.
Definition: IAkStreamMgr.h:209
AK::IAkStdStream::Write
virtual AKRESULT Write(void *in_pBuffer, AkUInt32 in_uReqSize, bool in_bWait, AkPriority in_priority, AkReal32 in_fDeadline, AkUInt32 &out_uSize)=0
AkAutoStmHeuristics::uMinNumBuffers
AkUInt8 uMinNumBuffers
Definition: IAkStreamMgr.h:128
AkAutoStmHeuristics
Automatic streams heuristics.
Definition: IAkStreamMgr.h:124
AK::IAkStreamMgr::UnpinFileInCache
virtual AKRESULT UnpinFileInCache(AkFileID in_fileID, AkPriority in_uPriority)=0
AkStreamRecord::bIsCachingStream
bool bIsCachingStream
True for caching streams.
Definition: IAkStreamMgr.h:194
AK::IAkStreamMgr::m_pStreamMgr
static IAkStreamMgr * m_pStreamMgr
Definition: IAkStreamMgr.h:866
AK::IAkStreamProfile::GetStreamRecord
virtual void GetStreamRecord(AkStreamRecord &out_streamRecord)=0
AkDeviceDesc::szDeviceName
AkUtf16 szDeviceName[AK_MONITOR_DEVICENAME_MAXLENGTH]
Device name.
Definition: IAkStreamMgr.h:157
AK_MONITOR_STREAMNAME_MAXLENGTH
#define AK_MONITOR_STREAMNAME_MAXLENGTH
Definition: IAkStreamMgr.h:41
AK::IAkDeviceProfile::IsNew
virtual bool IsNew()=0
AK::IAkStreamMgr::GetBufferStatusForPinnedFile
virtual AKRESULT GetBufferStatusForPinnedFile(AkFileID in_fileID, AkReal32 &out_fPercentBuffered, bool &out_bCacheFull)=0
AK::IAkStreamMgr::UpdateCachingPriority
virtual AKRESULT UpdateCachingPriority(AkFileID in_fileID, AkPriority in_uPriority, AkPriority in_uOldPriority)=0
AK::IAkAutoStream::GetFileDescriptor
virtual void * GetFileDescriptor()=0
AkStreamData::uFilePosition
AkUInt64 uFilePosition
Current position.
Definition: IAkStreamMgr.h:203
AK::IAkStdStream::GetPosition
virtual AkUInt64 GetPosition(bool *out_pbEndOfStream)=0
AK::IAkDeviceProfile::ClearNew
virtual void ClearNew()=0
AkFileSystemFlags::uCodecID
AkUInt32 uCodecID
File/codec type ID (defined in AkTypes.h)
Definition: IAkStreamMgr.h:96
AkFileSystemFlags::pCustomParam
void * pCustomParam
Custom parameter.
Definition: IAkStreamMgr.h:98
AK_StmStatusCancelled
@ AK_StmStatusCancelled
Operation cancelled.
Definition: IAkStreamMgr.h:55

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