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

このページはお役に立ちましたか？

サポートは必要ですか？

ご質問や問題、ご不明点はございますか？お気軽にお問い合わせください。

サポートページをご確認ください

あなたのプロジェクトについて教えてください。ご不明な点はありませんか。

プロジェクトを登録していただくことで、ご利用開始のサポートをいたします。

Wwiseからはじめよう