Wwise SDK 2017.1.9
_i_ak_stream_mgr_8h_source
Version
menu_open
link
include/AK/SoundEngine/Common/IAkStreamMgr.h
Go to the documentation of this file.00001 /******************************************************************************* 00002 The content of this file includes portions of the AUDIOKINETIC Wwise Technology 00003 released in source code form as part of the SDK installer package. 00004 00005 Commercial License Usage 00006 00007 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology 00008 may use this file in accordance with the end user license agreement provided 00009 with the software or, alternatively, in accordance with the terms contained in a 00010 written agreement between you and Audiokinetic Inc. 00011 00012 Apache License Usage 00013 00014 Alternatively, this file may be used under the Apache License, Version 2.0 (the 00015 "Apache License"); you may not use this file except in compliance with the 00016 Apache License. You may obtain a copy of the Apache License at 00017 http://www.apache.org/licenses/LICENSE-2.0. 00018 00019 Unless required by applicable law or agreed to in writing, software distributed 00020 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES 00021 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for 00022 the specific language governing permissions and limitations under the License. 00023 00024 Version: <VERSION> Build: <BUILDNUMBER> 00025 Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc. 00026 *******************************************************************************/ 00027 00028 /// \file 00029 /// Defines the API of Audiokinetic's I/O streaming solution. 00030 00031 #ifndef _IAK_STREAM_MGR_H_ 00032 #define _IAK_STREAM_MGR_H_ 00033 00034 #include <AK/SoundEngine/Common/AkMemoryMgr.h> 00035 00036 //----------------------------------------------------------------------------- 00037 // Defines. 00038 //----------------------------------------------------------------------------- 00039 00040 /// \name Profiling string lengths. 00041 //@{ 00042 #define AK_MONITOR_STREAMNAME_MAXLENGTH (64) 00043 #define AK_MONITOR_DEVICENAME_MAXLENGTH (16) 00044 //@} 00045 00046 //----------------------------------------------------------------------------- 00047 // Enums. 00048 //----------------------------------------------------------------------------- 00049 00050 /// Stream status. 00051 enum AkStmStatus 00052 { 00053 AK_StmStatusIdle = 0, ///< The stream is idle 00054 AK_StmStatusCompleted = 1, ///< Operation completed / Automatic stream reached end 00055 AK_StmStatusPending = 2, ///< Operation pending / The stream is waiting for I/O 00056 AK_StmStatusCancelled = 3, ///< Operation cancelled 00057 AK_StmStatusError = 4 ///< The low-level I/O reported an error 00058 }; 00059 00060 /// Move method for position change. 00061 /// \sa 00062 /// - AK::IAkStdStream::SetPosition() 00063 /// - AK::IAkAutoStream::SetPosition() 00064 enum AkMoveMethod 00065 { 00066 AK_MoveBegin = 0, ///< Move offset from the start of the stream 00067 AK_MoveCurrent = 1, ///< Move offset from the current stream position 00068 AK_MoveEnd = 2 ///< Move offset from the end of the stream 00069 }; 00070 00071 /// File open mode. 00072 enum AkOpenMode 00073 { 00074 AK_OpenModeRead = 0, ///< Read-only access 00075 AK_OpenModeWrite = 1, ///< Write-only access (opens the file if it already exists) 00076 AK_OpenModeWriteOvrwr = 2, ///< Write-only access (deletes the file if it already exists) 00077 AK_OpenModeReadWrite = 3 ///< Read and write access 00078 }; 00079 00080 /// File system flags for file descriptors mapping. 00081 struct AkFileSystemFlags 00082 { 00083 AkFileSystemFlags() 00084 : uCacheID( AK_INVALID_FILE_ID ) {} 00085 00086 AkFileSystemFlags( AkUInt32 in_uCompanyID, AkUInt32 in_uCodecID, AkUInt32 in_uCustomParamSize, void * in_pCustomParam, bool in_bIsLanguageSpecific, AkFileID in_uCacheID ) 00087 : uCompanyID( in_uCompanyID ) 00088 , uCodecID( in_uCodecID ) 00089 , uCustomParamSize( in_uCustomParamSize ) 00090 , pCustomParam( in_pCustomParam ) 00091 , bIsLanguageSpecific( in_bIsLanguageSpecific ) 00092 , uCacheID( in_uCacheID ) 00093 , uNumBytesPrefetch( 0 ) {} 00094 00095 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). 00096 AkUInt32 uCodecID; ///< File/codec type ID (defined in AkTypes.h) 00097 AkUInt32 uCustomParamSize; ///< Size of the custom parameter 00098 void * pCustomParam; ///< Custom parameter 00099 bool bIsLanguageSpecific;///< True when the file location depends on language 00100 bool bIsAutomaticStream; ///< True when the file is opened to be used as an automatic stream. Note that you don't need to set it. 00101 ///< If you pass an AkFileSystemFlags to IAkStreamMgr CreateStd|Auto(), it will be set internally to the correct value. 00102 AkFileID uCacheID; ///< Cache ID for caching system used by automatic streams. The user is responsible for guaranteeing unicity of IDs. 00103 ///< When set, it supersedes the file ID passed to AK::IAkStreamMgr::CreateAuto() (ID version). Caching is optional and depends on the implementation. 00104 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 00105 ///< AK::IAkStreamMgr::PinFileInCache() and AK::SoundEngine::PinEventInStreamCache(). When using AK::SoundEngine::PinEventInStreamCache(), 00106 ///< 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. 00107 }; 00108 00109 /// Stream information. 00110 /// \sa 00111 /// - AK::IAkStdStream::GetInfo() 00112 /// - AK::IAkAutoStream::GetInfo() 00113 struct AkStreamInfo 00114 { 00115 AkDeviceID deviceID; ///< Device ID 00116 const AkOSChar * pszName; ///< User-defined stream name (specified through AK::IAkStdStream::SetStreamName() or AK::IAkAutoStream::SetStreamName()) 00117 AkUInt64 uSize; ///< Total stream/file size in bytes 00118 bool bIsOpen; ///< True when the file is open (implementations may defer file opening) 00119 }; 00120 00121 /// Automatic streams heuristics. 00122 struct AkAutoStmHeuristics 00123 { 00124 AkReal32 fThroughput; ///< Average throughput in bytes/ms 00125 AkUInt32 uLoopStart; ///< Set to the start of loop (byte offset from the beginning of the stream) for streams that loop, 0 otherwise 00126 AkUInt32 uLoopEnd; ///< Set to the end of loop (byte offset from the beginning of the stream) for streams that loop, 0 otherwise 00127 AkUInt8 uMinNumBuffers; ///< Minimum number of buffers if you plan to own more than one buffer at a time, 0 or 1 otherwise 00128 ///< \remarks You should always release buffers as fast as possible, therefore this heuristic should be used only when 00129 ///< dealing with special contraints, like drivers or hardware that require more than one buffer at a time.\n 00130 ///< Also, this is only a heuristic: it does not guarantee that data will be ready when calling AK::IAkAutoStream::GetBuffer(). 00131 AkPriority priority; ///< The stream priority. it should be between AK_MIN_PRIORITY and AK_MAX_PRIORITY (included). 00132 }; 00133 00134 /// Automatic streams buffer settings/constraints. 00135 struct AkAutoStmBufSettings 00136 { 00137 AkUInt32 uBufferSize; ///< Hard user constraint: When non-zero, forces the I/O buffer to be of size uBufferSize 00138 ///< (overriding the device's granularity). 00139 ///< Otherwise, the size is determined by the device's granularity. 00140 AkUInt32 uMinBufferSize; ///< Soft user constraint: When non-zero, specifies a minimum buffer size 00141 ///< \remarks Ignored if uBufferSize is specified. 00142 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. 00143 }; 00144 00145 /// \name Profiling structures. 00146 //@{ 00147 00148 /// Device descriptor. 00149 struct AkDeviceDesc 00150 { 00151 AkDeviceID deviceID; ///< Device ID 00152 bool bCanWrite; ///< Specifies whether or not the device is writable 00153 bool bCanRead; ///< Specifies whether or not the device is readable 00154 AkUtf16 szDeviceName[AK_MONITOR_DEVICENAME_MAXLENGTH]; ///< Device name 00155 AkUInt32 uStringSize; ///< Device name string's size (number of characters) 00156 }; 00157 00158 /// Device descriptor. 00159 struct AkDeviceData 00160 { 00161 AkDeviceID deviceID; ///< Device ID 00162 AkUInt32 uMemSize; ///< IO memory pool size 00163 AkUInt32 uMemUsed; ///< IO memory pool used 00164 AkUInt32 uAllocs; ///< Cumulative number of allocations 00165 AkUInt32 uFrees; ///< Cumulative number of deallocations 00166 AkUInt32 uPeakRefdMemUsed; ///< Memory peak since monitoring started 00167 AkUInt32 uUnreferencedCachedBytes; ///< IO memory that is cached but is not currently used for active streams. 00168 AkUInt32 uGranularity; ///< IO memory pool block size 00169 AkUInt32 uNumActiveStreams; ///< Number of streams that have been active in the previous frame 00170 AkUInt32 uTotalBytesTransferred; ///< Number of bytes transferred, including cached transfers 00171 AkUInt32 uLowLevelBytesTransferred; ///< Number of bytes transferred exclusively via low-level 00172 AkReal32 fAvgCacheEfficiency; ///< Total bytes from cache as a percentage of total bytes. 00173 AkUInt32 uNumLowLevelRequestsCompleted; ///< Number of low-level transfers that have completed in the previous monitoring frame 00174 AkUInt32 uNumLowLevelRequestsCancelled; ///< Number of low-level transfers that were cancelled in the previous monitoring frame 00175 AkUInt32 uNumLowLevelRequestsPending; ///< Number of low-level transfers that are currently pending 00176 AkUInt32 uCustomParam; ///< Custom number queried from low-level IO. 00177 AkUInt32 uCachePinnedBytes; ///< Number of bytes that can be pinned into cache. 00178 }; 00179 00180 /// Stream general information. 00181 struct AkStreamRecord 00182 { 00183 AkUInt32 uStreamID; ///< Unique stream identifier 00184 AkDeviceID deviceID; ///< Device ID 00185 AkUtf16 szStreamName[AK_MONITOR_STREAMNAME_MAXLENGTH]; ///< Stream name 00186 AkUInt32 uStringSize; ///< Stream name string's size (number of characters) 00187 AkUInt64 uFileSize; ///< File size 00188 AkUInt32 uCustomParamSize; ///< File descriptor's uCustomParamSize 00189 AkUInt32 uCustomParam; ///< File descriptor's pCustomParam (on 32 bits) 00190 bool bIsAutoStream; ///< True for auto streams 00191 bool bIsCachingStream; ///< True for caching streams 00192 }; 00193 00194 /// Stream statistics. 00195 struct AkStreamData 00196 { 00197 AkUInt32 uStreamID; ///< Unique stream identifier 00198 // Status (replace) 00199 AkUInt32 uPriority; ///< Stream priority 00200 AkUInt64 uFilePosition; ///< Current position 00201 AkUInt32 uTargetBufferingSize; ///< Total stream buffer size (specific to IAkAutoStream) 00202 AkUInt32 uVirtualBufferingSize; ///< Size of available data including requested data (specific to IAkAutoStream) 00203 AkUInt32 uBufferedSize; ///< Size of available data (specific to IAkAutoStream) 00204 AkUInt32 uNumBytesTransfered; ///< Transfered amount since last query (Accumulate/Reset) 00205 AkUInt32 uNumBytesTransferedLowLevel;///< Transfered amount (from low-level IO only) since last query (Accumulate/Reset) 00206 AkUInt32 uMemoryReferenced; ///< Amount of streaming memory referenced by this stream 00207 AkReal32 fEstimatedThroughput; ///< Estimated throughput heuristic 00208 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 00209 }; 00210 //@} 00211 00212 namespace AK 00213 { 00214 /// \name Profiling interfaces. 00215 //@{ 00216 00217 /// Profiling interface of streams. 00218 /// \warning The functions in this interface are not thread-safe, unless stated otherwise. 00219 class IAkStreamProfile 00220 { 00221 protected: 00222 /// Virtual destructor on interface to avoid warnings. 00223 virtual ~IAkStreamProfile(){} 00224 00225 public: 00226 /// Returns the stream's record (once). 00227 /// \sa 00228 /// - \ref streamingdevicemanager 00229 virtual void GetStreamRecord( 00230 AkStreamRecord & out_streamRecord ///< Returned stream record interface 00231 ) = 0; 00232 00233 /// Returns the stream's statistics (every profile frame). 00234 /// \sa 00235 /// - \ref streamingdevicemanager 00236 virtual void GetStreamData( 00237 AkStreamData & out_streamData ///< Returned periodic stream data interface 00238 ) = 0; 00239 00240 /// Query the stream's "new" flag. 00241 /// \return True, until AK::IAkStreamProfile::ClearNew() is called. 00242 /// \sa 00243 /// - \ref streamingdevicemanager 00244 virtual bool IsNew() = 0; 00245 00246 /// Resets the stream's "new" flag. 00247 /// \sa 00248 /// - \ref streamingdevicemanager 00249 virtual void ClearNew() = 0; 00250 }; 00251 00252 00253 /// Profiling interface of high-level I/O devices. 00254 /// \warning The functions in this interface are not thread-safe, unless stated otherwise. 00255 class IAkDeviceProfile 00256 { 00257 protected: 00258 /// Virtual destructor on interface to avoid warnings. 00259 virtual ~IAkDeviceProfile(){} 00260 00261 public: 00262 00263 /// Notify device when monitor sampling starts. 00264 virtual void OnProfileStart() = 0; 00265 00266 /// Notify device when monitor sampling ends. 00267 virtual void OnProfileEnd() = 0; 00268 00269 /// Query the device's description (once). 00270 /// \sa 00271 /// - \ref streamingdevicemanager 00272 virtual void GetDesc( 00273 AkDeviceDesc & out_deviceDesc ///< Device descriptor. 00274 ) = 0; 00275 00276 /// Query the device's statistics (at every profiling frame). 00277 /// \sa 00278 /// - \ref streamingdevicemanager 00279 virtual void GetData( 00280 AkDeviceData & out_deviceData ///< Device data. 00281 ) = 0; 00282 00283 /// Query the device's "new" flag. 00284 /// \return True, until ClearNew() is called. 00285 /// \sa 00286 /// - \ref streamingdevicemanager 00287 virtual bool IsNew() = 0; 00288 00289 /// Resets the device's "new" flag. 00290 /// \sa 00291 /// - \ref streamingdevicemanager 00292 virtual void ClearNew() = 0; 00293 00294 /// Get the number of streams currently associated with that device. 00295 /// \return The number of streams 00296 /// \sa 00297 /// - \ref streamingdevicemanager 00298 virtual AkUInt32 GetNumStreams() = 0; 00299 00300 /// Get a stream profile, for a specified stream index. 00301 /// \remarks GetStreamProfile() refers to streams by index, which must honor the call to AK::IAkDeviceProfile::GetNumStreams(). 00302 /// \sa 00303 /// - \ref streamingdevicemanager 00304 virtual IAkStreamProfile * GetStreamProfile( 00305 AkUInt32 in_uStreamIndex ///< Stream index: [0,numStreams[ 00306 ) = 0; 00307 }; 00308 00309 /// Profiling interface of the Stream Manager. 00310 /// \warning The functions in this interface are not thread-safe, unless stated otherwise. 00311 class IAkStreamMgrProfile 00312 { 00313 protected: 00314 /// Virtual destructor on interface to avoid warnings. 00315 virtual ~IAkStreamMgrProfile(){} 00316 00317 public: 00318 /// Start profile monitoring. 00319 /// \return AK_Success if successful, AK_Fail otherwise. 00320 /// \sa 00321 /// - \ref streamingdevicemanager 00322 virtual AKRESULT StartMonitoring() = 0; 00323 00324 /// Stop profile monitoring. 00325 /// \sa 00326 /// - \ref streamingdevicemanager 00327 virtual void StopMonitoring() = 0; 00328 00329 /// Device enumeration. 00330 /// \return The number of devices. 00331 /// \sa 00332 /// - \ref streamingdevicemanager 00333 virtual AkUInt32 GetNumDevices() = 0; 00334 00335 /// Get a device profile for a specified device index. 00336 /// \remarks GetDeviceProfile() refers to devices by index, which must honor the call to AK::IAkStreamMgrProfile::GetNumDevices(). 00337 /// \remarks The device index is not the same as the device ID (AkDeviceID). 00338 /// \sa 00339 /// - \ref streamingdevicemanager 00340 virtual IAkDeviceProfile * GetDeviceProfile( 00341 AkUInt32 in_uDeviceIndex ///< Device index: [0,numDevices[ 00342 ) = 0; 00343 }; 00344 //@} 00345 00346 /// \name High-level streams API. 00347 //@{ 00348 00349 /// Interface of standard streams. Used as a handle to a standard stream. Has methods for 00350 /// stream control. Obtained through the Stream Manager's AK::IAkStreamMgr::CreateStd() method. 00351 /// \warning The functions in this interface are not thread-safe, unless stated otherwise. 00352 class IAkStdStream 00353 { 00354 protected: 00355 /// Virtual destructor on interface to avoid warnings. 00356 virtual ~IAkStdStream(){} 00357 00358 public: 00359 /// \name Stream management and settings. 00360 //@{ 00361 /// Close the stream. The object is destroyed and the interface becomes invalid. 00362 /// \sa 00363 /// - \ref streamingdevicemanager 00364 virtual void Destroy() = 0; 00365 00366 /// Get information about a stream. 00367 /// \sa 00368 /// - \ref streamingdevicemanager 00369 virtual void GetInfo( 00370 AkStreamInfo & out_info ///< Returned stream info 00371 ) = 0; 00372 00373 /// Returns a unique cookie for a given stream. 00374 /// The default implementation of the Stream Manager returns its file descriptor (see AkStreamMgrModule.h). 00375 virtual void * GetFileDescriptor() = 0; 00376 00377 /// Give the stream a name (appears in the Wwise Profiler). 00378 /// \sa 00379 /// - \ref streamingdevicemanager 00380 virtual AKRESULT SetStreamName( 00381 const AkOSChar * in_pszStreamName ///< Stream name 00382 ) = 0; 00383 00384 /// Get the I/O block size. 00385 /// \remark Queries the low-level I/O, by calling AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize() with the 00386 /// stream's file descriptor. 00387 /// \return The block size, in bytes. 00388 /// \sa 00389 /// - \ref streamingdevicemanager 00390 virtual AkUInt32 GetBlockSize() = 0; 00391 //@} 00392 00393 /// \name I/O operations. 00394 //@{ 00395 00396 /// Schedule a read request. 00397 /// \warning Use only with a multiple of the block size, queried via AK::IAkStdStream::GetBlockSize(). 00398 /// \remarks If the call is asynchronous (in_bWait = false), wait until AK::IAkStdStream::GetStatus() stops returning AK_StmStatusPending. 00399 /// \return AK_Success if the operation was successfully scheduled (but not necessarily completed) 00400 /// \sa 00401 /// - \ref streamingdevicemanager 00402 virtual AKRESULT Read( 00403 void * in_pBuffer, ///< User buffer address 00404 AkUInt32 in_uReqSize, ///< Requested read size 00405 bool in_bWait, ///< Block until the operation is complete 00406 AkPriority in_priority, ///< Heuristic: operation priority 00407 AkReal32 in_fDeadline, ///< Heuristic: operation deadline (ms) 00408 AkUInt32 & out_uSize ///< The size that was actually read 00409 ) = 0; 00410 00411 /// Schedule a write request. 00412 /// \warning Use only with a multiple of the block size, queried via AK::IAkStdStream::GetBlockSize(). 00413 /// \remarks If the call is asynchronous (in_bWait = false), wait until GetStatus() stops returning AK_StmStatusPending. 00414 /// \return AK_Success if the operation was successfully scheduled 00415 /// \sa 00416 /// - \ref streamingdevicemanager 00417 virtual AKRESULT Write( 00418 void * in_pBuffer, ///< User buffer address 00419 AkUInt32 in_uReqSize, ///< Requested write size 00420 bool in_bWait, ///< Block until the operation is complete 00421 AkPriority in_priority, ///< Heuristic: operation priority 00422 AkReal32 in_fDeadline, ///< Heuristic: operation deadline (ms) 00423 AkUInt32 & out_uSize ///< The size that was actually written 00424 ) = 0; 00425 00426 /// Get the current stream position. 00427 /// \remarks If an operation is pending, there is no guarantee that the position was queried before (or after) the operation was completed. 00428 /// \return The current stream position 00429 /// \sa 00430 /// - \ref streamingdevicemanager 00431 virtual AkUInt64 GetPosition( 00432 bool * out_pbEndOfStream ///< Returned end-of-stream flag, only for streams opened with AK_OpenModeRead (can pass NULL) 00433 ) = 0; 00434 00435 /// Set the stream position. Modifies the position for the next read/write operation. 00436 /// \warning No operation should be pending. 00437 /// \remarks The new position will snap to the lowest block boundary. 00438 /// \return AK_Success if the stream position was changed 00439 /// \sa 00440 /// - \ref streamingdevicemanager 00441 virtual AKRESULT SetPosition( 00442 AkInt64 in_iMoveOffset, ///< Seek offset 00443 AkMoveMethod in_eMoveMethod, ///< Seek method, from the beginning, end, or current file position 00444 AkInt64 * out_piRealOffset ///< The actual seek offset may differ from the expected value when the block size is bigger than 1. 00445 ///< In that case, the seek offset floors to the sector boundary. Can pass NULL. 00446 ) = 0; 00447 00448 /// Cancel the current operation. 00449 /// \remarks When it returns, the caller is guaranteed that no operation is pending. 00450 /// \remarks This method can block the caller for the whole duration of the I/O operation, if the request was already posted. 00451 /// \sa 00452 /// - \ref streamingdevicemanager 00453 virtual void Cancel() = 0; 00454 00455 //@} 00456 00457 /// \name Access to data and status. 00458 //@{ 00459 /// Get user data (and accessed size). 00460 /// \return The address of data provided by user 00461 /// \sa 00462 /// - \ref streamingdevicemanager 00463 virtual void * GetData( 00464 AkUInt32 & out_uSize ///< Size actually read or written 00465 ) = 0; 00466 00467 /// Get the stream's status. 00468 /// \return The stream status. 00469 /// \sa 00470 /// - \ref streamingdevicemanager 00471 virtual AkStmStatus GetStatus() = 0; 00472 00473 //@} 00474 }; 00475 00476 00477 /// Interface of automatic streams. It is used as a handle to a stream, 00478 /// I/O operations are triggered from here. 00479 /// Obtained through the Stream Manager's AK::IAkStreamMgr::CreateAuto() method. 00480 /// \warning The functions in this interface are not thread-safe, unless stated otherwise. 00481 /// \sa 00482 /// - \ref streamingdevicemanager 00483 class IAkAutoStream 00484 { 00485 protected: 00486 /// Virtual destructor on interface to avoid warnings. 00487 virtual ~IAkAutoStream(){} 00488 00489 public: 00490 /// \name Stream management, settings access, and run-time change. 00491 //@{ 00492 /// Close the stream. The object is destroyed and the interface becomes invalid. 00493 /// \sa 00494 /// - \ref streamingdevicemanager 00495 virtual void Destroy() = 0; 00496 00497 /// Get information about the stream. 00498 /// \sa 00499 /// - \ref streamingdevicemanager 00500 virtual void GetInfo( 00501 AkStreamInfo & out_info ///< Returned stream info 00502 ) = 0; 00503 00504 /// Returns a unique cookie for a given stream. 00505 /// The default implementation of the Stream Manager returns its file descriptor (see AkStreamMgrModule.h). 00506 virtual void * GetFileDescriptor() = 0; 00507 00508 /// Get the stream's heuristics. 00509 /// \sa 00510 /// - \ref streamingdevicemanager 00511 virtual void GetHeuristics( 00512 AkAutoStmHeuristics & out_heuristics///< Returned stream heuristics 00513 ) = 0; 00514 00515 /// Run-time change of the stream's heuristics. 00516 /// \sa 00517 /// - \ref streamingdevicemanager 00518 virtual AKRESULT SetHeuristics( 00519 const AkAutoStmHeuristics & in_heuristics ///< New stream heuristics 00520 ) = 0; 00521 00522 /// Run-time change of the stream's minimum buffer size that can be handed out to client 00523 /// in GetBuffer() (except the last buffer at the end of file). 00524 /// Corresponds to the uMinBufferSize field of the AkAutoStmBufSettings passed to CreateAuto(). 00525 /// \sa 00526 /// - AkAutoStmBufSettings 00527 /// - \ref streamingdevicemanager 00528 virtual AKRESULT SetMinimalBufferSize( 00529 AkUInt32 in_uMinBufferSize ///< Minimum buffer size that can be handed out to client. 00530 ) = 0; 00531 00532 /// Give the stream a name (appears in the Wwise profiler). 00533 /// \sa 00534 /// - \ref streamingdevicemanager 00535 virtual AKRESULT SetStreamName( 00536 const AkOSChar * in_pszStreamName ///< Stream name 00537 ) = 0; 00538 00539 /// Get the I/O block size. 00540 /// \remark Queries the actual low-level I/O device, by calling AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize() with the 00541 /// stream's file descriptor. 00542 /// \return The block size (in bytes) 00543 /// \sa 00544 /// - \ref streamingdevicemanager 00545 virtual AkUInt32 GetBlockSize() = 0; 00546 00547 /// Get the amount of buffering that the stream has. 00548 /// The buffering is defined as the number of bytes that the stream has buffered, excluding the number 00549 /// of bytes that is currently granted to the user (with GetBuffer()). 00550 /// \remark The returned value corresponds to the buffering status at that moment, and does not even 00551 /// guarantee that it will not shrink. 00552 /// \return 00553 /// - AK_DataReady: Some data has been buffered (out_uNumBytesAvailable is greater than 0). 00554 /// - AK_NoDataReady: No data is available, and the end of file has not been reached. 00555 /// - AK_NoMoreData: Some or no data is available, but the end of file has been reached. The stream will not buffer any more data. 00556 /// - AK_Fail: The stream is invalid due to an I/O error. 00557 virtual AKRESULT QueryBufferingStatus( 00558 AkUInt32 & out_uNumBytesAvailable ///< Number of bytes available in the stream's buffer(s). 00559 ) = 0; 00560 00561 /// Returns the target buffering size based on the throughput heuristic. 00562 /// \return 00563 /// Target buffering length expressed in bytes. 00564 virtual AkUInt32 GetNominalBuffering() = 0; 00565 00566 //@} 00567 00568 /// \name Stream operations. 00569 //@{ 00570 00571 /// Start the automatic scheduling. 00572 /// \return AK_Success if the automatic scheduling was started successfully 00573 /// \sa 00574 /// - \ref streamingdevicemanager 00575 virtual AKRESULT Start() = 0; 00576 00577 /// Stop the automatic scheduling. 00578 /// \return AK_Success if the automatic scheduling was stopped successfully. 00579 /// \sa 00580 /// - \ref streamingdevicemanager 00581 virtual AKRESULT Stop() = 0; 00582 00583 /// Get the stream's position. 00584 /// \remarks The stream position is the position seen by the user, not the position of the file 00585 /// already streamed into the Stream Manager's memory. The stream position is updated when buffers 00586 /// are released, using AK::IAkAutoStream::ReleaseBuffer(). 00587 /// \return The file position in bytes of the beginning of the first buffer owned by the user. 00588 /// If the user does not own a buffer, it returns the position of the beginning of the buffer that 00589 /// would be returned from a call to AK::IAkAutoStream::GetBuffer(). 00590 /// \sa 00591 /// - \ref streamingdevicemanager 00592 virtual AkUInt64 GetPosition( 00593 bool * out_pbEndOfStream ///< Returned end-of-stream flag (can pass NULL) 00594 ) = 0; 00595 00596 /// Set the stream's position. 00597 /// The next call to AK::IAkAutoStream::GetBuffer() will grant data that corresponds to the position specified here. 00598 /// \remarks Data already streamed into the Stream Manager's memory might be flushed. 00599 /// \remarks The new position will round down to the low-level I/O block size. 00600 /// \return AK_Success if the resulting position is valid 00601 /// \sa 00602 /// - \ref streamingdevicemanager 00603 virtual AKRESULT SetPosition( 00604 AkInt64 in_iMoveOffset, ///< Seek offset 00605 AkMoveMethod in_eMoveMethod, ///< Seek method, from the beginning, end or current file position 00606 AkInt64 * out_piRealOffset ///< The actual seek offset may differ from the expected value when the low-level's block size is greater than 1. 00607 ///< In that case, the real absolute position rounds down to the block boundary. Can pass NULL. 00608 ) = 0; 00609 00610 //@} 00611 00612 00613 /// \name Data/status access. 00614 //@{ 00615 00616 /// Get data from the Stream Manager buffers. 00617 /// \remarks Grants a buffer if data is available. Each successful call to this method returns a new 00618 /// buffer of data, at the current stream position. 00619 /// Buffers should be released as soon as they are not needed, using AK::IAkAutoStream::ReleaseBuffer(). 00620 /// \aknote AK::IAkAutoStream::ReleaseBuffer() does not take any argument, because it releases buffers in order. \endaknote 00621 /// \return 00622 /// - AK_DataReady : the buffer was granted 00623 /// - AK_NoDataReady : the buffer is not granted yet (never happens when called with in_bWait flag) 00624 /// - AK_NoMoreData : the buffer was granted but reached end of file (next call will return with size 0) 00625 /// - AK_Fail : there was an I/O error 00626 /// \sa 00627 /// - \ref streamingdevicemanager 00628 virtual AKRESULT GetBuffer( 00629 void *& out_pBuffer, ///< Returned address of granted data space 00630 AkUInt32 & out_uSize, ///< Returned size of granted data space 00631 bool in_bWait ///< Block until data is ready 00632 ) = 0; 00633 00634 /// Release buffer granted through GetBuffer(). Buffers are released in order. 00635 /// \return AK_Success if a valid buffer was released, AK_Fail if the user did not own any buffer. 00636 /// \note To implementers: Clients like the sound engine may release buffers until this function returns AK_Fail. 00637 /// Failing to release a buffer should not be considered as a fatal error. 00638 /// \sa 00639 /// - \ref streamingdevicemanager 00640 virtual AKRESULT ReleaseBuffer() = 0; 00641 //@} 00642 }; 00643 00644 //@} 00645 00646 00647 /// Interface of the Stream Manager. 00648 /// \warning The functions in this interface are not thread-safe, unless stated otherwise. 00649 class IAkStreamMgr 00650 { 00651 protected: 00652 /// Virtual destructor on interface to avoid warnings. 00653 virtual ~IAkStreamMgr(){} 00654 00655 public: 00656 /// Global access to singleton. 00657 /// \return The interface of the global Stream Manager 00658 /// \sa 00659 /// - \ref streamingdevicemanager 00660 inline static IAkStreamMgr * Get() 00661 { 00662 return m_pStreamMgr; 00663 } 00664 00665 /// Destroy the Stream Manager. 00666 /// \sa 00667 /// - \ref streamingdevicemanager 00668 virtual void Destroy() = 0; 00669 00670 00671 /// \name Profiling. 00672 //@{ 00673 /// Get the profiling interface. 00674 /// \return The interface of the Stream Manager profiler 00675 virtual IAkStreamMgrProfile * GetStreamMgrProfile() = 0; 00676 //@} 00677 00678 00679 /// \name Stream creation interface. 00680 //@{ 00681 00682 // Standard stream creation methods. 00683 00684 /// Create a standard stream (string overload). 00685 /// \return AK_Success if the stream was created successfully 00686 /// \remarks The string overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called. 00687 /// \sa 00688 /// - \ref streamingdevicemanager 00689 virtual AKRESULT CreateStd( 00690 const AkOSChar* in_pszFileName, ///< Application-defined string (title only, or full path, or code...) 00691 AkFileSystemFlags * in_pFSFlags, ///< Special file system flags. Can pass NULL 00692 AkOpenMode in_eOpenMode, ///< Open mode (read, write, ...) 00693 IAkStdStream *& out_pStream, ///< Returned interface to a standard stream. If the function does not return AK_Success, this pointer is left untouched. 00694 bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion. 00695 ) = 0; 00696 00697 /// Create a standard stream (ID overload). 00698 /// \return AK_Success if the stream was created successfully 00699 /// \remarks The ID overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called. 00700 /// \sa 00701 /// - \ref streamingdevicemanager 00702 virtual AKRESULT CreateStd( 00703 AkFileID in_fileID, ///< Application-defined ID 00704 AkFileSystemFlags * in_pFSFlags, ///< Special file system flags (can pass NULL) 00705 AkOpenMode in_eOpenMode, ///< Open mode (read, write, ...) 00706 IAkStdStream *& out_pStream, ///< Returned interface to a standard stream. If the function does not return AK_Success, this pointer is left untouched. 00707 bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion. 00708 ) = 0; 00709 00710 00711 // Automatic stream create methods. 00712 00713 /// Create an automatic stream (string overload). 00714 /// \return AK_Success if the stream was created successfully 00715 /// \remarks The stream needs to be started explicitly with AK::IAkAutoStream::Start(). 00716 /// \remarks The string overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called. 00717 /// \sa 00718 /// - \ref streamingdevicemanager 00719 virtual AKRESULT CreateAuto( 00720 const AkOSChar* in_pszFileName, ///< Application-defined string (title only, or full path, or code...) 00721 AkFileSystemFlags * in_pFSFlags, ///< Special file system flags (can pass NULL) 00722 const AkAutoStmHeuristics & in_heuristics, ///< Streaming heuristics 00723 AkAutoStmBufSettings * in_pBufferSettings, ///< Stream buffer settings (it is recommended to pass NULL in order to use the default settings) 00724 IAkAutoStream *& out_pStream, ///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched. 00725 bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion. 00726 ) = 0; 00727 00728 /// Create an automatic stream (ID overload). 00729 /// \return AK_Success if the stream was created successfully 00730 /// \remarks The stream needs to be started explicitly with IAkAutoStream::Start(). 00731 /// \remarks The ID overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called. 00732 /// \sa 00733 /// - \ref streamingdevicemanager 00734 virtual AKRESULT CreateAuto( 00735 AkFileID in_fileID, ///< Application-defined ID 00736 AkFileSystemFlags * in_pFSFlags, ///< Special file system flags (can pass NULL) 00737 const AkAutoStmHeuristics & in_heuristics, ///< Streaming heuristics 00738 AkAutoStmBufSettings * in_pBufferSettings, ///< Stream buffer settings (it is recommended to pass NULL to use the default settings) 00739 IAkAutoStream *& out_pStream, ///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched. 00740 bool in_bSyncOpen ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion. 00741 ) = 0; 00742 00743 /// Start streaming the first "in_pFSFlags->uNumBytesPrefetch" bytes of the file with id "in_fileID" into cache. The stream will be scheduled only after 00744 /// all regular streams (not file caching streams) are serviced. The file will stay cached until either the UnpinFileInCache is called, 00745 /// or the limit as set by uMaxCachePinnedBytes is reached and another higher priority file (in_uPriority) needs the space. 00746 /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API. 00747 /// 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. 00748 /// 00749 /// \sa 00750 /// - \ref streamingdevicemanager 00751 /// - AK::SoundEngine::PinEventInStreamCache 00752 /// - AK::SoundEngine::UnpinEventInStreamCache 00753 /// - AkFileSystemFlags 00754 virtual AKRESULT PinFileInCache( 00755 AkFileID in_fileID, ///< Application-defined ID 00756 AkFileSystemFlags * in_pFSFlags, ///< Special file system flags (can NOT pass NULL) 00757 AkPriority in_uPriority ///< Stream caching priority. Note: Caching requests only get serviced after all regular streaming requests. 00758 ) = 0; 00759 00760 /// 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. 00761 /// 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 00762 /// cache management algorithm. 00763 /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API. 00764 /// Using UnpinFileInCache() directly does not allow users to take advantage of sound bank data. The file must be explicitly specified. 00765 /// \sa 00766 /// - \ref streamingdevicemanager 00767 /// - AK::SoundEngine::PinEventInStreamCache 00768 /// - AK::SoundEngine::UnpinEventInStreamCache 00769 virtual AKRESULT UnpinFileInCache( 00770 AkFileID in_fileID, ///< Application-defined ID 00771 AkPriority in_uPriority ///< Priority of stream that you are unpinning 00772 ) = 0; 00773 00774 /// 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 00775 /// memory if the cache pin limit as set by "uMaxCachePinnedBytes" is reached. 00776 /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API. 00777 /// Using UpdateCachingPriority() directly does not allow users to take advantage of sound bank data. The file must be explicitly specified. 00778 /// \sa 00779 /// - \ref streamingdevicemanager 00780 /// - AK::SoundEngine::PinEventInStreamCache 00781 /// - AK::SoundEngine::UnpinEventInStreamCache 00782 virtual AKRESULT UpdateCachingPriority( 00783 AkFileID in_fileID, ///< Application-defined ID 00784 AkPriority in_uPriority, ///< Priority 00785 AkPriority in_uOldPriority ///< Old priority 00786 ) = 0; 00787 00788 /// Return information about a file that has been pinned into cache. 00789 /// Retrieves the percentage of the requested buffer size that has been streamed in and stored into stream cache, and whether 00790 /// the cache pinned memory limit is preventing this buffer from filling. 00791 virtual AKRESULT GetBufferStatusForPinnedFile( 00792 AkFileID in_fileID, ///< Application-defined ID 00793 AkReal32& out_fPercentBuffered, ///< Percentage of buffer full (out of 100) 00794 bool& out_bCacheFull ///< Set to true if the rest of the buffer can not fit into the cache-pinned memory limit. 00795 ) = 0; 00796 00797 //@} 00798 00799 protected: 00800 /// Definition of the global pointer to the interface of the Stream Manager singleton. 00801 /// \sa 00802 /// - \ref streamingdevicemanager 00803 static AKSOUNDENGINE_API IAkStreamMgr * m_pStreamMgr; 00804 }; 00805 00806 } 00807 #endif //_IAK_STREAM_MGR_H_
Was this page helpful?
Need Support?
Questions? Problems? Need more info? Contact us, and we can help!
Visit our Support pageTell 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