Table des matières

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         /// Set the minimum size to buffer ahead in an automated stream.
00533         ///
00534         /// 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.
00535         /// The system will predict the minimum size to buffer and will consider this value as the minimal size to be the target.
00536         /// \sa
00537         /// - AkAutoStmBufSettings
00538         /// - \ref streamingdevicemanager
00539         /// - \ref AkAutoStmHeuristics
00540         virtual AKRESULT  SetMinTargetBufferSize(
00541             AkUInt32        in_uMinTargetBufferSize ///< Minimum size to buffer ahead in an automated stream. (in bytes)
00542         ) = 0;
00543 
00544         /// Give the stream a name (appears in the Wwise profiler).
00545         /// \sa
00546         /// - \ref streamingdevicemanager
00547         virtual AKRESULT  SetStreamName(
00548             const AkOSChar *    in_pszStreamName    ///< Stream name
00549             ) = 0;
00550 
00551         /// Get the I/O block size.
00552         /// \remark Queries the actual low-level I/O device, by calling AK::StreamMgr::IAkLowLevelIOHook::GetBlockSize() with the
00553         /// stream's file descriptor.
00554         /// \return The block size (in bytes)
00555         /// \sa
00556         /// - \ref streamingdevicemanager
00557         virtual AkUInt32  GetBlockSize() = 0;
00558 
00559         /// Get the amount of buffering that the stream has. 
00560         /// The buffering is defined as the number of bytes that the stream has buffered, excluding the number
00561         /// of bytes that is currently granted to the user (with GetBuffer()).
00562         /// \remark The returned value corresponds to the buffering status at that moment, and does not even 
00563         /// guarantee that it will not shrink.
00564         /// \return 
00565         /// - AK_DataReady: Some data has been buffered (out_uNumBytesAvailable is greater than 0).
00566         /// - AK_NoDataReady: No data is available, and the end of file has not been reached.
00567         /// - AK_NoMoreData: Some or no data is available, but the end of file has been reached. The stream will not buffer any more data.
00568         /// - AK_Fail: The stream is invalid due to an I/O error.
00569         virtual AKRESULT QueryBufferingStatus( 
00570             AkUInt32 & out_uNumBytesAvailable   ///< Number of bytes available in the stream's buffer(s).
00571             ) = 0;
00572 
00573         /// Returns the target buffering size based on the throughput heuristic.
00574         /// \return
00575         /// Target buffering length expressed in bytes. 
00576         virtual AkUInt32 GetNominalBuffering() = 0;
00577 
00578         //@}
00579 
00580         /// \name Stream operations.
00581         //@{
00582         
00583         /// Start the automatic scheduling.
00584         /// \return AK_Success if the automatic scheduling was started successfully
00585         /// \sa
00586         /// - \ref streamingdevicemanager
00587         virtual AKRESULT Start() = 0;
00588 
00589         /// Stop the automatic scheduling.
00590         /// \return AK_Success if the automatic scheduling was stopped successfully.
00591         /// \sa
00592         /// - \ref streamingdevicemanager
00593         virtual AKRESULT Stop() = 0;
00594 
00595         /// Get the stream's position.
00596         /// \remarks The stream position is the position seen by the user, not the position of the file
00597         /// already streamed into the Stream Manager's memory. The stream position is updated when buffers 
00598         /// are released, using AK::IAkAutoStream::ReleaseBuffer().
00599         /// \return The file position in bytes of the beginning of the first buffer owned by the user. 
00600         /// If the user does not own a buffer, it returns the position of the beginning of the buffer that 
00601         /// would be returned from a call to AK::IAkAutoStream::GetBuffer().
00602         /// \sa
00603         /// - \ref streamingdevicemanager
00604         virtual AkUInt64 GetPosition( 
00605             bool *          out_pbEndOfStream   ///< Returned end-of-stream flag (can pass NULL)
00606             ) = 0;  
00607 
00608         /// Set the stream's position. 
00609         /// The next call to AK::IAkAutoStream::GetBuffer() will grant data that corresponds to the position specified here.
00610         /// \remarks Data already streamed into the Stream Manager's memory might be flushed.
00611         /// \remarks The new position will round down to the low-level I/O block size.
00612         /// \return AK_Success if the resulting position is valid
00613         /// \sa
00614         /// - \ref streamingdevicemanager
00615         virtual AKRESULT SetPosition(
00616             AkInt64         in_iMoveOffset,     ///< Seek offset
00617             AkMoveMethod    in_eMoveMethod,     ///< Seek method, from the beginning, end or current file position
00618             AkInt64 *       out_piRealOffset    ///< The actual seek offset may differ from the expected value when the low-level's block size is greater than 1.
00619                                                 ///< In that case, the real absolute position rounds down to the block boundary. Can pass NULL.
00620             ) = 0;
00621 
00622         //@}
00623 
00624 
00625         /// \name Data/status access.
00626         //@{
00627 
00628         /// Get data from the Stream Manager buffers.
00629         /// \remarks Grants a buffer if data is available. Each successful call to this method returns a new 
00630         /// buffer of data, at the current stream position.
00631         /// Buffers should be released as soon as they are not needed, using AK::IAkAutoStream::ReleaseBuffer().
00632         /// \aknote AK::IAkAutoStream::ReleaseBuffer() does not take any argument, because it releases buffers in order. \endaknote
00633         /// \return
00634         ///     - AK_DataReady     : the buffer was granted
00635         ///     - AK_NoDataReady   : the buffer is not granted yet (never happens when called with in_bWait flag)
00636         ///     - AK_NoMoreData    : the buffer was granted but reached end of file (next call will return with size 0)
00637         ///     - AK_Fail          : there was an I/O error
00638         /// \sa
00639         /// - \ref streamingdevicemanager
00640         virtual AKRESULT GetBuffer(
00641             void *&         out_pBuffer,        ///< Returned address of granted data space
00642             AkUInt32 &      out_uSize,          ///< Returned size of granted data space
00643             bool            in_bWait            ///< Block until data is ready
00644             ) = 0;
00645 
00646         /// Release buffer granted through GetBuffer(). Buffers are released in order.
00647         /// \return AK_Success if a valid buffer was released, AK_Fail if the user did not own any buffer.
00648         /// \note To implementers: Clients like the sound engine may release buffers until this function returns AK_Fail.
00649         /// Failing to release a buffer should not be considered as a fatal error.
00650         /// \sa
00651         /// - \ref streamingdevicemanager
00652         virtual AKRESULT ReleaseBuffer() = 0;
00653         //@}
00654     };
00655 
00656     //@}
00657 
00658 
00659     /// Interface of the Stream Manager.
00660     /// \warning The functions in this interface are not thread-safe, unless stated otherwise.
00661     class IAkStreamMgr
00662     {
00663     protected:
00664         /// Virtual destructor on interface to avoid warnings.
00665         virtual ~IAkStreamMgr(){}
00666         
00667     public:
00668         /// Global access to singleton.
00669         /// \return The interface of the global Stream Manager
00670         /// \sa
00671         /// - \ref streamingdevicemanager
00672         inline static IAkStreamMgr * Get()
00673         {
00674             return m_pStreamMgr;
00675         }
00676 
00677         /// Destroy the Stream Manager.
00678         /// \sa
00679         /// - \ref streamingdevicemanager
00680         virtual void     Destroy() = 0;
00681 
00682 
00683         /// \name Profiling.
00684         //@{
00685         /// Get the profiling interface.
00686         /// \return The interface of the Stream Manager profiler
00687         virtual IAkStreamMgrProfile * GetStreamMgrProfile() = 0;
00688         //@}
00689 
00690 
00691         /// \name Stream creation interface.
00692         //@{
00693         
00694         // Standard stream creation methods.
00695 
00696         /// Create a standard stream (string overload).
00697         /// \return AK_Success if the stream was created successfully
00698         /// \remarks The string overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
00699         /// \sa
00700         /// - \ref streamingdevicemanager
00701         virtual AKRESULT CreateStd(
00702             const AkOSChar*     in_pszFileName,     ///< Application-defined string (title only, or full path, or code...)
00703             AkFileSystemFlags * in_pFSFlags,        ///< Special file system flags. Can pass NULL
00704             AkOpenMode          in_eOpenMode,       ///< Open mode (read, write, ...)
00705             IAkStdStream *&     out_pStream,        ///< Returned interface to a standard stream. If the function does not return AK_Success, this pointer is left untouched.
00706             bool                in_bSyncOpen        ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
00707             ) = 0;
00708 
00709         /// Create a standard stream (ID overload).
00710         /// \return AK_Success if the stream was created successfully
00711         /// \remarks The ID overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
00712         /// \sa
00713         /// - \ref streamingdevicemanager
00714         virtual AKRESULT CreateStd(
00715             AkFileID            in_fileID,          ///< Application-defined ID
00716             AkFileSystemFlags * in_pFSFlags,        ///< Special file system flags (can pass NULL)
00717             AkOpenMode          in_eOpenMode,       ///< Open mode (read, write, ...)
00718             IAkStdStream *&     out_pStream,        ///< Returned interface to a standard stream. If the function does not return AK_Success, this pointer is left untouched.
00719             bool                in_bSyncOpen        ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
00720             ) = 0;
00721 
00722         
00723         // Automatic stream create methods.
00724 
00725         /// Create an automatic stream (string overload).
00726         /// \return AK_Success if the stream was created successfully
00727         /// \remarks The stream needs to be started explicitly with AK::IAkAutoStream::Start().
00728         /// \remarks The string overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
00729         /// \sa
00730         /// - \ref streamingdevicemanager
00731         virtual AKRESULT CreateAuto(
00732             const AkOSChar*             in_pszFileName,     ///< Application-defined string (title only, or full path, or code...)
00733             AkFileSystemFlags *         in_pFSFlags,        ///< Special file system flags (can pass NULL)
00734             const AkAutoStmHeuristics & in_heuristics,      ///< Streaming heuristics
00735             AkAutoStmBufSettings *      in_pBufferSettings, ///< Stream buffer settings (it is recommended to pass NULL in order to use the default settings)
00736             IAkAutoStream *&            out_pStream,        ///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched.
00737             bool                        in_bSyncOpen        ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
00738             ) = 0;
00739 
00740         /// Create an automatic stream (ID overload).
00741         /// \return AK_Success if the stream was created successfully
00742         /// \remarks The stream needs to be started explicitly with IAkAutoStream::Start().
00743         /// \remarks The ID overload of AK::StreamMgr::IAkFileLocationResolver::Open() will be called.
00744         /// \sa
00745         /// - \ref streamingdevicemanager
00746         virtual AKRESULT CreateAuto(
00747             AkFileID                    in_fileID,          ///< Application-defined ID
00748             AkFileSystemFlags *         in_pFSFlags,        ///< Special file system flags (can pass NULL)
00749             const AkAutoStmHeuristics & in_heuristics,      ///< Streaming heuristics
00750             AkAutoStmBufSettings *      in_pBufferSettings, ///< Stream buffer settings (it is recommended to pass NULL to use the default settings)
00751             IAkAutoStream *&            out_pStream,        ///< Returned interface to an automatic stream. If the function does not return AK_Success, this pointer is left untouched.
00752             bool                        in_bSyncOpen        ///< If true, force the Stream Manager to open file synchronously. Otherwise, it is left to its discretion.
00753             ) = 0;
00754 
00755         /// Start streaming the first "in_pFSFlags->uNumBytesPrefetch" bytes of the file with id "in_fileID" into cache.  The stream will be scheduled only after
00756         /// all regular streams (not file caching streams) are serviced.  The file will stay cached until either the UnpinFileInCache is called,
00757         /// or the limit as set by uMaxCachePinnedBytes is reached and another higher priority file (in_uPriority) needs the space.  
00758         /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API. 
00759         ///     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.
00760         /// 
00761         /// \sa
00762         /// - \ref streamingdevicemanager
00763         /// - AK::SoundEngine::PinEventInStreamCache
00764         /// - AK::SoundEngine::UnpinEventInStreamCache
00765         /// - AkFileSystemFlags
00766         virtual AKRESULT PinFileInCache(
00767             AkFileID                    in_fileID,          ///< Application-defined ID
00768             AkFileSystemFlags *         in_pFSFlags,        ///< Special file system flags (can NOT pass NULL)
00769             AkPriority                  in_uPriority        ///< Stream caching priority.  Note: Caching requests only get serviced after all regular streaming requests.
00770             ) = 0;
00771 
00772         /// 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.
00773         /// 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 
00774         /// cache management algorithm.
00775         /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API. 
00776         ///     Using UnpinFileInCache() directly does not allow users to take advantage of sound bank data.  The file must be explicitly specified.
00777         /// \sa
00778         /// - \ref streamingdevicemanager
00779         /// - AK::SoundEngine::PinEventInStreamCache
00780         /// - AK::SoundEngine::UnpinEventInStreamCache
00781         virtual AKRESULT UnpinFileInCache(
00782             AkFileID                    in_fileID,              ///< Application-defined ID
00783             AkPriority                  in_uPriority        ///< Priority of stream that you are unpinning
00784             ) = 0;
00785         
00786         /// 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 
00787         /// memory if the cache pin limit as set by "uMaxCachePinnedBytes" is reached.
00788         /// \remarks PinFileInCache()/UnpinFileInCache()/UpdateCachingPriority() are typically not used directly, but instead used via the AK::SoundEngine::PinEventInStreamCache() API. 
00789         ///     Using UpdateCachingPriority() directly does not allow users to take advantage of sound bank data.  The file must be explicitly specified.
00790         /// \sa
00791         /// - \ref streamingdevicemanager
00792         /// - AK::SoundEngine::PinEventInStreamCache
00793         /// - AK::SoundEngine::UnpinEventInStreamCache
00794         virtual AKRESULT UpdateCachingPriority(
00795             AkFileID                    in_fileID,          ///< Application-defined ID
00796             AkPriority                  in_uPriority,       ///< Priority
00797             AkPriority                  in_uOldPriority         ///< Old priority
00798             ) = 0;
00799         
00800         /// Return information about a file that has been pinned into cache.
00801         /// Retrieves the percentage of the requested buffer size that has been streamed in and stored into stream cache, and whether 
00802         /// the cache pinned memory limit is preventing this buffer from filling.
00803         virtual AKRESULT GetBufferStatusForPinnedFile( 
00804             AkFileID in_fileID,                             ///< Application-defined ID
00805             AkReal32& out_fPercentBuffered,                 ///< Percentage of buffer full (out of 100)
00806             bool& out_bCacheFull                            ///< Set to true if the rest of the buffer can not fit into the cache-pinned memory limit.
00807             ) = 0;
00808 
00809         //@}
00810 
00811     protected:
00812         /// Definition of the global pointer to the interface of the Stream Manager singleton.
00813         /// \sa
00814         /// - \ref streamingdevicemanager
00815         static AKSOUNDENGINE_API IAkStreamMgr * m_pStreamMgr;
00816     };
00817 
00818 }
00819 #endif //_IAK_STREAM_MGR_H_