using System;
using System.Runtime.InteropServices;
using static Vanara.PInvoke.Ole32;
using static Vanara.PInvoke.Winmm;
namespace Vanara.PInvoke
{
/// Functions, structures and constants from Windows Core Audio Api.
public static partial class CoreAudio
{
///
/// Specifies the type of an ISpatialAudioObject. A spatial audio object can be dynamic, meaning that it's spatial properties can
/// change over time, or static, which means that its spatial properties are fixed. There are 17 audio channels to which a static
/// spatial audio object can be assigned, each representing a real or virtualized speaker. The static channel values of the
/// enumeration can be combined as a mask to assign a spatial audio object to multiple channels. All of the enumeration values
/// except for AudioObjectType_None and AudioObjectType_Dynamic represent static channels.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/ne-spatialaudioclient-audioobjecttype typedef enum
// AudioObjectType { AudioObjectType_None, AudioObjectType_Dynamic, AudioObjectType_FrontLeft, AudioObjectType_FrontRight,
// AudioObjectType_FrontCenter, AudioObjectType_LowFrequency, AudioObjectType_SideLeft, AudioObjectType_SideRight,
// AudioObjectType_BackLeft, AudioObjectType_BackRight, AudioObjectType_TopFrontLeft, AudioObjectType_TopFrontRight,
// AudioObjectType_TopBackLeft, AudioObjectType_TopBackRight, AudioObjectType_BottomFrontLeft, AudioObjectType_BottomFrontRight,
// AudioObjectType_BottomBackLeft, AudioObjectType_BottomBackRight, AudioObjectType_BackCenter } ;
[PInvokeData("spatialaudioclient.h", MSDNShortId = "DFFE770F-41C0-4048-A38F-FB96353E9216")]
public enum AudioObjectType
{
/// The spatial audio object is not spatialized.
AudioObjectType_None = 0,
/// The spatial audio object is dynamic. It's spatial properties can be changed over time.
AudioObjectType_Dynamic = (1 << 0),
///
/// The spatial audio object is assigned the front left channel. The equivalent channel mask of DirectShow's
/// WAVEFORMATEXTENSIBLE enumeration is SPEAKER_FRONT_LEFT.
///
AudioObjectType_FrontLeft = (1 << 1),
///
/// The spatial audio object is assigned the front right channel. The equivalent channel mask of DirectShow's
/// WAVEFORMATEXTENSIBLE enumeration is SPEAKER_FRONT_RIGHT.
///
AudioObjectType_FrontRight = (1 << 2),
///
/// The spatial audio object is assigned the front center channel. The equivalent channel mask of DirectShow's
/// WAVEFORMATEXTENSIBLE enumeration is SPEAKER_FRONT_CENTER.
///
AudioObjectType_FrontCenter = (1 << 3),
///
/// The spatial audio object is assigned the low frequency channel. Because this channel is not spatialized, it does not count
/// toward the system resource limits for spatialized audio objects. The equivalent channel mask of DirectShow's
/// WAVEFORMATEXTENSIBLE enumeration is SPEAKER_LOW_FREQUENCY.
///
AudioObjectType_LowFrequency = (1 << 4),
///
/// The spatial audio object is assigned the side left channel. The equivalent channel mask of DirectShow's WAVEFORMATEXTENSIBLE
/// enumeration is SPEAKER_SIDE_LEFT.
///
AudioObjectType_SideLeft = (1 << 5),
///
/// The spatial audio object is assigned the side right channel. The equivalent channel mask of DirectShow's
/// WAVEFORMATEXTENSIBLE enumeration is SPEAKER_SIDE_RIGHT.
///
AudioObjectType_SideRight = (1 << 6),
///
/// The spatial audio object is assigned the back left channel. The equivalent channel mask of DirectShow's WAVEFORMATEXTENSIBLE
/// enumeration is SPEAKER_BACK_LEFT.
///
AudioObjectType_BackLeft = (1 << 7),
///
/// The spatial audio object is assigned the back right channel. The equivalent channel mask of DirectShow's
/// WAVEFORMATEXTENSIBLE enumeration is SPEAKER_BACK_RIGHT.
///
AudioObjectType_BackRight = (1 << 8),
///
/// The spatial audio object is assigned the top front left channel. The equivalent channel mask of DirectShow's
/// WAVEFORMATEXTENSIBLE enumeration is SPEAKER_TOP_FRONT_LEFT.
///
AudioObjectType_TopFrontLeft = (1 << 9),
///
/// The spatial audio object is assigned the top front right channel. The equivalent channel mask of DirectShow's
/// WAVEFORMATEXTENSIBLE enumeration is SPEAKER_TOP_FRONT_RIGHT.
///
AudioObjectType_TopFrontRight = (1 << 10),
///
/// The spatial audio object is assigned the top back left channel. The equivalent channel mask of DirectShow's
/// WAVEFORMATEXTENSIBLE enumeration is SPEAKER_TOP_BACK_LEFT.
///
AudioObjectType_TopBackLeft = (1 << 11),
///
/// The spatial audio object is assigned the top back right channel. The equivalent channel mask of DirectShow's
/// WAVEFORMATEXTENSIBLE enumeration is SPEAKER_TOP_BACK_RIGHT.
///
AudioObjectType_TopBackRight = (1 << 12),
/// The spatial audio object is assigned the bottom front left channel.
AudioObjectType_BottomFrontLeft = (1 << 13),
/// The spatial audio object is assigned the bottom front right channel.
AudioObjectType_BottomFrontRight = (1 << 14),
/// The spatial audio object is assigned the bottom back left channel.
AudioObjectType_BottomBackLeft = (1 << 15),
/// The spatial audio object is assigned the bottom back right channel.
AudioObjectType_BottomBackRight = (1 << 16),
/// The spatial audio object is assigned the back center channel.
AudioObjectType_BackCenter = (1 << 17)
}
///
/// Provides a list of supported audio formats. The most preferred format is first in the list. Get a reference to this interface by
/// calling ISpatialAudioClient::GetSupportedAudioObjectFormatEnumerator.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nn-spatialaudioclient-iaudioformatenumerator
[ComImport, Guid("DCDAA858-895A-4A22-A5EB-67BDA506096D"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IAudioFormatEnumerator
{
/// Gets the number of supported audio formats in the list
/// The number of supported audio formats in the list.
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-iaudioformatenumerator-getcount
// HRESULT GetCount( UINT32 *count );
uint GetCount();
///
/// Gets the format with the specified index in the list. The formats are listed in order of importance. The most preferable
/// format is first in the list.
///
/// The index of the item in the list to retrieve.
/// Pointer to a pointer to a WAVEFORMATEX structure describing a supported audio format.
/// If the method succeeds, it returns S_OK.
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-iaudioformatenumerator-getformat
// HRESULT GetFormat( UINT32 index, WAVEFORMATEX **format );
void GetFormat([In] uint index, out IntPtr format);
}
///
/// The ISpatialAudioClient interface enables a client to create audio streams that emit audio from a position in 3D space.
/// This interface is a part of Windows Sonic, Microsoft’s audio platform for more immersive audio which includes integrated spatial
/// sound on Xbox and Windows.
///
///
///
/// Get an instance of this interface by calling ActivateAudioInterfaceAsync, using the __uuidof operator to get the class ID of the
/// ISpatialAudioClient interface. The following example code shows how to initialize this interface.
///
///
/// Note When using the ISpatialAudioClient interfaces on an Xbox One Development Kit (XDK) title, you must first call
/// EnableSpatialAudio before calling IMMDeviceEnumerator::EnumAudioEndpoints or
/// IMMDeviceEnumerator::GetDefaultAudioEndpoint. Failure to do so will result in an E_NOINTERFACE error being returned from the
/// call to Activate. EnableSpatialAudio is only available for XDK titles, and does not need to be called for Universal
/// Windows Platform apps running on Xbox One, nor for any non-Xbox One devices.
///
/// To access the ActivateAudioIntefaceAsync, you will need to link to mmdevapi.lib.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nn-spatialaudioclient-ispatialaudioclient
[PInvokeData("spatialaudioclient.h", MSDNShortId = "950778D4-79FE-4222-951F-5A456A633124")]
[ComImport, Guid("BBF8E066-AAAA-49BE-9A4D-FD2A858EA27F"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface ISpatialAudioClient
{
/// Gets the position in 3D space of the specified static spatial audio channel.
///
/// A value indicating the static spatial audio channel for which the position is being queried. This method will return
/// E_INVALIDARG if the value does not represent a static channel, including AudioObjectType_Dynamic and AudioObjectType_None.
///
///
/// The x coordinate of the static audio channel, in meters, relative to the listener. Positive values are to the right of the
/// listener and negative values are to the left.
///
///
/// The y coordinate of the static audio channel, in meters, relative to the listener. Positive values are above the listener
/// and negative values are below.
///
///
/// The z coordinate of the static audio channel, in meters, relative to the listener. Positive values are behind the listener
/// and negative values are in front.
///
///
/// Position values use a right-handed Cartesian coordinate system, where each unit represents 1 meter. The coordinate system is
/// relative to the listener where the origin (x=0.0, y=0.0, z=0.0) represents the center point between the listener's ears.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioclient-getstaticobjectposition
// HRESULT GetStaticObjectPosition( AudioObjectType type, float *x, float *y, float *z );
void GetStaticObjectPosition([In] AudioObjectType type, out float x, out float y, out float z);
/// Gets a channel mask which represents the subset of static speaker bed channels native to current rendering engine.
///
/// A bitwise combination of values from the AudioObjectType enumeration indicating a subset of static speaker channels. The
/// values returned will only include the static channel values and will not include AudioObjectType_Dynamic.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioclient-getnativestaticobjecttypemask
// HRESULT GetNativeStaticObjectTypeMask( AudioObjectType *mask );
AudioObjectType GetNativeStaticObjectTypeMask();
/// Gets the maximum number of dynamic audio objects for the spatial audio client.
/// Gets the maximum dynamic object count for this client.
///
///
/// A dynamic ISpatialAudioObject is one that was activated by setting the type parameter to the
/// ISpatialAudioObjectRenderStream::ActivateSpatialAudioObject method to AudioObjectType_Dynamic. The client has a limit
/// of the maximum number of dynamic spatial audio objects that can be activated at one time. When the capacity of the audio
/// rendering pipeline changes, the system will dynamically adjust the maximum number of concurrent dynamic spatial audio
/// objects. Before doing so, the system will call OnAvailableDynamicObjectCountChange to notify clients of the resource limit change.
///
///
/// Call Release on an ISpatialAudioObject when it is no longer being used to free up the resource to create new dynamic
/// spatial audio objects.
///
///
/// When Windows Sonic is not available (for instance, when playing to embedded laptop stereo speakers, or if the user has not
/// explicitly enabled Windows Sonic on the device), the number of available dynamic objects returned by
/// GetMaxDynamicObjectCount to an application will be 0.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioclient-getmaxdynamicobjectcount
// HRESULT GetMaxDynamicObjectCount( UINT32 *value );
uint GetMaxDynamicObjectCount();
///
/// Gets an IAudioFormatEnumerator that contains all supported audio formats for spatial audio objects, the first item in the
/// list represents the most preferable format.
///
/// Pointer to the pointer that receives the IAudioFormatEnumerator interface.
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioclient-getsupportedaudioobjectformatenumerator
// HRESULT GetSupportedAudioObjectFormatEnumerator( IAudioFormatEnumerator **enumerator );
IAudioFormatEnumerator GetSupportedAudioObjectFormatEnumerator();
///
/// Gets the maximum possible frame count per processing pass. This method can be used to determine the size of the source
/// buffer that should be allocated to convey audio data for each processing pass.
///
///
/// The audio format used to calculate the maximum frame count. This should be the same format specified in the
/// ObjectFormat field of the SpatialAudioObjectRenderStreamActivationParams passed to ActivateSpatialAudioStream.
///
/// The maximum number of audio frames that will be processed in one pass.
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioclient-getmaxframecount
// HRESULT GetMaxFrameCount( const WAVEFORMATEX *objectFormat, UINT32 *frameCountPerBuffer );
uint GetMaxFrameCount(in WAVEFORMATEX objectFormat);
/// Gets a value indicating whether ISpatialAudioObjectRenderStream supports a the specified format.
/// The format for which support is queried.
///
/// If the specified format is supported, it returns S_OK. If specified format is unsupported, this method returns AUDCLNT_E_UNSUPPORTED_FORMAT.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioclient-isaudioobjectformatsupported
// HRESULT IsAudioObjectFormatSupported( const WAVEFORMATEX *objectFormat );
[PreserveSig]
HRESULT IsAudioObjectFormatSupported(in WAVEFORMATEX objectFormat);
///
/// When successful, gets a value indicating whether the currently active spatial rendering engine supports the specified
/// spatial audio render stream.
///
/// The interface ID of the interface for which availability is queried.
///
/// A structure containing additional information to be used when support is queried. For more information, see Remarks.
///
///
///
/// If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values
/// shown in the following table.
///
///
///
/// Return code
/// Description
///
/// -
/// SPTLAUDCLNT_E_STREAM_IS_NOT_AVAILABLE
/// The specified stream interface can't be activated by the currently active rendering engine.
///
/// -
/// SPTLAUDCLNT_E_METADATA_FORMAT_IS_NOT_SUPPORTED
///
/// The metadata format supplied in the auxiliaryInfo parameter is not supported by the current rendering engine. For more
/// information, see Remarks..
///
///
///
///
///
///
/// When querying to see if the ISpatialAudioObjectRenderStreamForMetadata you can use the auxilaryInfo parameter to query if a
/// particular metadata format is supported. The following code example demonstrates how to initialize the PROPVARIANT structure
/// to check for support for an example metadata format.
///
/// If the specified metadata format is unsupported, IsSpatialAudioStreamAvailable returns SPTLAUDCLNT_E_METADATA_FORMAT_IS_NOT_SUPPORTED.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioclient-isspatialaudiostreamavailable
// HRESULT IsSpatialAudioStreamAvailable( REFIID streamUuid, const PROPVARIANT *auxiliaryInfo );
[PreserveSig]
HRESULT IsSpatialAudioStreamAvailable(in Guid streamUuid, [In, Optional] PROPVARIANT auxiliaryInfo);
/// Activates and initializes spatial audio stream using one of the spatial audio stream activation structures.
///
/// The structure defining the activation parameters for the spatial audio stream. The vt field should be set to VT_BLOB
/// and the blob field should be populated with a SpatialAudioObjectRenderStreamActivationParams or a SpatialAudioObjectRenderStreamForMetadataActivationParams.
///
/// The UUID of the spatial audio stream interface to activate.
/// A pointer which receives the activated spatial audio interface.
///
/// This method supports activation of the following spatial audio stream interfaces:
/// ISpatialAudioObjectRenderStream
/// ISpatialAudioObjectRenderStreamForMetadata
/// Examples
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioclient-activatespatialaudiostream
// HRESULT ActivateSpatialAudioStream( const PROPVARIANT *activationParams, REFIID riid, void **stream );
[return: MarshalAs(UnmanagedType.IUnknown, IidParameterIndex = 1)]
object ActivateSpatialAudioStream([In] PROPVARIANT activationParams, in Guid riid);
}
///
///
/// Represents an object that provides audio data to be rendered from a position in 3D space, relative to the user. Spatial audio
/// objects can be static or dynamic, which you specify with the type parameter to the
/// ISpatialAudioObjectRenderStream::ActivateSpatialAudioObject method. Dynamic audio objects can be placed in an arbitrary position
/// in space and can be moved over time. Static audio objects are assigned to one or more channels, defined in the AudioObjectType
/// enumeration, that each correlate to a fixed speaker location that may be a physical or a virtualized speaker.
///
///
/// This interface is a part of Windows Sonic, Microsoft’s audio platform for more immersive audio which includes integrated spatial
/// sound on Xbox and Windows.
///
///
///
/// Note Many of the methods provided by this interface are implemented in the inherited ISpatialAudioObjectBase interface.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nn-spatialaudioclient-ispatialaudioobject
[PInvokeData("spatialaudioclient.h", MSDNShortId = "EE83AF5F-4342-4CF2-81A7-1123F8DAFA6F")]
[ComImport, Guid("DDE28967-521B-46E5-8F00-BD6F2BC8AB1D"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface ISpatialAudioObject : ISpatialAudioObjectBase
{
/// Gets a buffer that is used to supply the audio data for the ISpatialAudioObject.
/// The buffer into which audio data is written.
///
/// The length of the buffer in bytes. This length will be the value returned in the frameCountPerBuffer parameter to
/// ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects multiplied by the value of the nBlockAlign field of the
/// WAVEFORMATEX structure passed in the SpatialAudioObjectRenderStreamActivationParams parameter to ISpatialAudioClient::ActivateSpatialAudioStream.
///
///
///
/// The first time GetBuffer is called after the ISpatialAudioObject is activated with a call
/// ISpatialAudioObjectRenderStream::ActivateSpatialAudioObject, lifetime of the spatial audio object starts. To keep the
/// spatial audio object alive after that, this GetBuffer must be called on every processing pass (between calls to
/// ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects and ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects). If
/// GetBuffer is not called within an audio processing pass, SetEndOfStream is called implicitly on the audio object to
/// deactivate, and the audio object can only be reused after calling Release on the object and then reactivating the object by
/// calling ActivateSpatialAudioObject again.
///
///
/// The pointers retrieved by GetBuffer should not be used after ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects
/// has been called.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectbase-getbuffer
// HRESULT GetBuffer( BYTE **buffer, UINT32 *bufferLength );
new void GetBuffer(out IntPtr buffer, out uint bufferLength);
///
/// Instructs the system that the final block of audio data has been submitted for the ISpatialAudioObject so that the object
/// can be deactivated and it's resources reused.
///
///
/// The number of audio frames in the audio buffer that should be included in the final processing pass. This number may be
/// smaller than or equal to the value returned in the frameCountPerBuffer parameter to ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects.
///
///
///
/// If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values
/// shown in the following table.
///
///
///
/// Return code
/// Description
///
/// -
/// SPTLAUDCLNT_E_OUT_OF_ORDER
/// ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects was not called before the call to SetEndOfStream.
///
/// -
/// SPTLAUDCLNT_E_RESOURCES_INVALIDATED
///
/// SetEndOfStream was called either explicitly or implicitly in a previous audio processing pass. SetEndOfStream is called
/// implicitly by the system if GetBuffer is not called within an audio processing pass (between calls to
/// ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects and ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects).
///
///
///
///
/// Call Release after calling SetEndOfStream to make free the audio object resources for future use.
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectbase-setendofstream
// HRESULT SetEndOfStream( UINT32 frameCount );
new void SetEndOfStream([In] uint frameCount);
/// Gets a boolean value indicating whether the ISpatialAudioObject is valid.
/// TRUE if the audio object is currently valid; otherwise, FALSE.
///
/// If this value is false, you should call Release to make the audio object resource available in the future.
///
/// IsActive will be set to false after SetEndOfStream is called implicitly or explicitly. SetEndOfStream is
/// called implicitly by the system if GetBuffer is not called within an audio processing pass (between calls to
/// ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects and ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects).
///
///
/// The rendering engine will also deactivate the audio object, setting IsActive to false, when audio object resources
/// become unavailable. In this case, a notification is sent via ISpatialAudioObjectRenderStreamNotify before the object is
/// deactivated. The value returned in the availableDynamicObjectCount parameter to
/// ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects indicates how many objects will be processed for each pass.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectbase-isactive
// HRESULT IsActive( BOOL *isActive );
[return: MarshalAs(UnmanagedType.Bool)]
new bool IsActive();
///
/// Gets a value specifying the type of audio object that is represented by the ISpatialAudioObject. This value indicates if the
/// object is dynamic or static. If the object is static, one and only one of the static audio channel values to which the
/// object is assigned is returned.
///
/// A value specifying the type of audio object that is represented
///
/// Set the type of the audio object with the type parameter to the ISpatialAudioObjectRenderStream::ActivateSpatialAudioObject method.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectbase-getaudioobjecttype
// HRESULT GetAudioObjectType( AudioObjectType *audioObjectType );
new AudioObjectType GetAudioObjectType();
///
/// Sets the position in 3D space, relative to the listener, from which the ISpatialAudioObject audio data will be rendered.
///
///
/// The x position of the audio object, in meters, relative to the listener. Positive values are to the right of the listener
/// and negative values are to the left.
///
///
/// The y position of the audio object, in meters, relative to the listener. Positive values are above the listener and negative
/// values are below.
///
///
/// The z position of the audio object, in meters, relative to the listener. Positive values are behind the listener and
/// negative values are in front.
///
///
///
/// If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values
/// shown in the following table.
///
///
///
/// Return code
/// Description
///
/// -
/// SPTLAUDCLNT_E_OUT_OF_ORDER
/// ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects was not called before the call to SetPosition.
///
/// -
/// SPTLAUDCLNT_E_RESOURCES_INVALIDATED
///
/// SetEndOfStream was called either explicitly or implicitly in a previous audio processing pass. SetEndOfStream is called
/// implicitly by the system if GetBuffer is not called within an audio processing pass (between calls to
/// ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects and ISpatialAudioObjectRenderStreamBase::EndUpdatingAudioObjects).
///
///
/// -
/// SPTLAUDCLNT_E_PROPERTY_NOT_SUPPORTED
///
/// The ISpatialAudioObject is not of type AudioObjectType_Dynamic. Set the type of the audio object with the type parameter to
/// the ISpatialAudioObjectRenderStreamBase::ActivateSpatialAudioObject method.
///
///
///
///
///
///
/// This method can only be called on a ISpatialAudioObject that is of type AudioObjectType_Dynamic. Set the type of the
/// audio object with the type parameter to the ISpatialAudioObjectRenderStreamBase::ActivateSpatialAudioObject method.
///
///
/// Position values use a right-handed Cartesian coordinate system, where each unit represents 1 meter. The coordinate system is
/// relative to the listener where the origin (x=0.0, y=0.0, z=0.0) represents the center point between the listener's ears.
///
///
/// If SetPosition is never called, the origin (x=0.0, y=0.0, z=0.0) is used as the default position. After
/// SetPosition is called, the position that is set will be used for the audio object until the position is changed with
/// another call to SetPosition.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobject-setposition
// HRESULT SetPosition( float x, float y, float z );
void SetPosition([In] float x, [In] float y, [In] float z);
///
/// Sets an audio amplitude multiplier that will be applied to the audio data provided by the ISpatialAudioObject before it is
/// submitted to the audio rendering engine.
///
/// The amplitude multiplier for audio data. This must be a value between 0.0 and 1.0.
///
///
/// If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values
/// shown in the following table.
///
///
///
/// Return code
/// Description
///
/// -
/// SPTLAUDCLNT_E_OUT_OF_ORDER
/// ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects was not called before the call to SetVolume.
///
/// -
/// SPTLAUDCLNT_E_RESOURCES_INVALIDATED
///
/// SetEndOfStream was called either explicitly or implicitly in a previous audio processing pass. SetEndOfStream is called
/// implicitly by the system if GetBuffer is not called within an audio processing pass (between calls to
/// ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects and ISpatialAudioObjectRenderStreamBase::EndUpdatingAudioObjects).
///
///
///
///
///
/// If SetVolume is never called, the default value of 1.0 is used. After SetVolume is called, the volume that is
/// set will be used for the audio object until the volume is changed with another call to SetVolume.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobject-setvolume
// HRESULT SetVolume( float volume );
void SetVolume([In] float volume);
}
///
///
/// Base interface that represents an object that provides audio data to be rendered from a position in 3D space, relative to the
/// user. Spatial audio objects can be static or dynamic, which you specify with the type parameter to the
/// ISpatialAudioObjectRenderStream::ActivateSpatialAudioObject method. Dynamic audio objects can be placed in an arbitrary position
/// in space and can be moved over time. Static audio objects are assigned to one or more channels, defined in the AudioObjectType
/// enumeration, that each correlate to a fixed speaker location that may be a physical or a virtualized speaker.
///
///
/// This interface is a part of Windows Sonic, Microsoft’s audio platform for more immersive audio which includes integrated spatial
/// sound on Xbox and Windows.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nn-spatialaudioclient-ispatialaudioobjectbase
[PInvokeData("spatialaudioclient.h", MSDNShortId = "54721875-D93A-4C7E-A07E-C286E1A409D3")]
[ComImport, Guid("CCE0B8F2-8D4D-4EFB-A8CF-3D6ECF1C30E0"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface ISpatialAudioObjectBase
{
/// Gets a buffer that is used to supply the audio data for the ISpatialAudioObject.
/// The buffer into which audio data is written.
///
/// The length of the buffer in bytes. This length will be the value returned in the frameCountPerBuffer parameter to
/// ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects multiplied by the value of the nBlockAlign field of the
/// WAVEFORMATEX structure passed in the SpatialAudioObjectRenderStreamActivationParams parameter to ISpatialAudioClient::ActivateSpatialAudioStream.
///
///
///
/// The first time GetBuffer is called after the ISpatialAudioObject is activated with a call
/// ISpatialAudioObjectRenderStream::ActivateSpatialAudioObject, lifetime of the spatial audio object starts. To keep the
/// spatial audio object alive after that, this GetBuffer must be called on every processing pass (between calls to
/// ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects and ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects). If
/// GetBuffer is not called within an audio processing pass, SetEndOfStream is called implicitly on the audio object to
/// deactivate, and the audio object can only be reused after calling Release on the object and then reactivating the object by
/// calling ActivateSpatialAudioObject again.
///
///
/// The pointers retrieved by GetBuffer should not be used after ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects
/// has been called.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectbase-getbuffer
// HRESULT GetBuffer( BYTE **buffer, UINT32 *bufferLength );
void GetBuffer(out IntPtr buffer, out uint bufferLength);
///
/// Instructs the system that the final block of audio data has been submitted for the ISpatialAudioObject so that the object
/// can be deactivated and it's resources reused.
///
///
/// The number of audio frames in the audio buffer that should be included in the final processing pass. This number may be
/// smaller than or equal to the value returned in the frameCountPerBuffer parameter to ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects.
///
///
///
/// If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values
/// shown in the following table.
///
///
///
/// Return code
/// Description
///
/// -
/// SPTLAUDCLNT_E_OUT_OF_ORDER
/// ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects was not called before the call to SetEndOfStream.
///
/// -
/// SPTLAUDCLNT_E_RESOURCES_INVALIDATED
///
/// SetEndOfStream was called either explicitly or implicitly in a previous audio processing pass. SetEndOfStream is called
/// implicitly by the system if GetBuffer is not called within an audio processing pass (between calls to
/// ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects and ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects).
///
///
///
///
/// Call Release after calling SetEndOfStream to make free the audio object resources for future use.
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectbase-setendofstream
// HRESULT SetEndOfStream( UINT32 frameCount );
void SetEndOfStream([In] uint frameCount);
/// Gets a boolean value indicating whether the ISpatialAudioObject is valid.
/// TRUE if the audio object is currently valid; otherwise, FALSE.
///
/// If this value is false, you should call Release to make the audio object resource available in the future.
///
/// IsActive will be set to false after SetEndOfStream is called implicitly or explicitly. SetEndOfStream is
/// called implicitly by the system if GetBuffer is not called within an audio processing pass (between calls to
/// ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects and ISpatialAudioObjectRenderStream::EndUpdatingAudioObjects).
///
///
/// The rendering engine will also deactivate the audio object, setting IsActive to false, when audio object resources
/// become unavailable. In this case, a notification is sent via ISpatialAudioObjectRenderStreamNotify before the object is
/// deactivated. The value returned in the availableDynamicObjectCount parameter to
/// ISpatialAudioObjectRenderStream::BeginUpdatingAudioObjects indicates how many objects will be processed for each pass.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectbase-isactive
// HRESULT IsActive( BOOL *isActive );
[return: MarshalAs(UnmanagedType.Bool)]
bool IsActive();
///
/// Gets a value specifying the type of audio object that is represented by the ISpatialAudioObject. This value indicates if the
/// object is dynamic or static. If the object is static, one and only one of the static audio channel values to which the
/// object is assigned is returned.
///
/// A value specifying the type of audio object that is represented
///
/// Set the type of the audio object with the type parameter to the ISpatialAudioObjectRenderStream::ActivateSpatialAudioObject method.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectbase-getaudioobjecttype
// HRESULT GetAudioObjectType( AudioObjectType *audioObjectType );
AudioObjectType GetAudioObjectType();
}
///
///
/// Provides methods for controlling a spatial audio object render stream, including starting, stopping, and resetting the stream.
/// Also provides methods for activating new ISpatialAudioObject instances and notifying the system when you are beginning and
/// ending the process of updating activated spatial audio objects and data.
///
///
/// This interface is a part of Windows Sonic, Microsoft’s audio platform for more immersive audio which includes integrated spatial
/// sound on Xbox and Windows.
///
///
///
/// Note Many of the methods provided by this interface are implemented in the inherited ISpatialAudioObjectRenderStreamBase interface.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nn-spatialaudioclient-ispatialaudioobjectrenderstream
[ComImport, Guid("BAB5F473-B423-477B-85F5-B5A332A04153"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface ISpatialAudioObjectRenderStream : ISpatialAudioObjectRenderStreamBase
{
/// Gets the number of dynamic spatial audio objects that are currently available.
/// The number of dynamic spatial audio objects that are currently available.
///
///
/// A dynamic ISpatialAudioObject is one that was activated by setting the type parameter to the ActivateSpatialAudioObject
/// method to AudioObjectType_Dynamic. The system has a limit of the maximum number of dynamic spatial audio objects that
/// can be activated at one time. Call Release on an ISpatialAudioObject when it is no longer being used to free up the
/// resource to create new dynamic spatial audio objects.
///
///
/// You should not call this method after streaming has started, as the value is already provided by
/// ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects. This method should only be called before streaming has
/// started, which occurs after ISpatialAudioObjectRenderStreamBase::Start is called.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-getavailabledynamicobjectcount
// HRESULT GetAvailableDynamicObjectCount( UINT32 *value );
new uint GetAvailableDynamicObjectCount();
/// Gets additional services from the ISpatialAudioObjectRenderStream.
///
/// The interface ID for the requested service. The client should set this parameter to one of the following REFIID values:
/// IID_IAudioClock
/// IID_IAudioClock2
/// IID_IAudioStreamVolume
///
///
/// Pointer to a pointer variable into which the method writes the address of an instance of the requested interface. Through
/// this method, the caller obtains a counted reference to the interface. The caller is responsible for releasing the interface,
/// when it is no longer needed, by calling the interface's Release method. If the GetService call fails, *ppv is NULL.
///
///
///
/// If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values
/// shown in the following table.
///
///
///
/// Return code
/// Description
///
/// -
/// E_POINTER
/// Parameter ppv is NULL.
///
/// -
/// SPTLAUDCLNT_E_DESTROYED
/// The ISpatialAudioClient associated with the spatial audio stream has been destroyed.
///
/// -
/// AUDCLNT_E_DEVICE_INVALIDATED
///
/// The audio endpoint device has been unplugged, or the audio hardware or associated hardware resources have been reconfigured,
/// disabled, removed, or otherwise made unavailable for use.
///
///
/// -
/// SPTLAUDCLNT_E_INTERNAL
/// An internal error has occurred.
///
/// -
/// AUDCLNT_E_UNSUPPORTED_FORMAT
/// The media associated with the spatial audio stream uses an unsupported format.
///
///
///
///
/// The GetService method supports the following service interfaces:
///
/// -
/// IAudioClock
///
/// -
/// IAudioClock2
///
/// -
/// IAudioStreamVolume
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-getservice
// HRESULT GetService( REFIID riid, void **service );
[PreserveSig]
new HRESULT GetService(in Guid riid, [MarshalAs(UnmanagedType.IUnknown, IidParameterIndex = 0)] out object service);
/// Starts the spatial audio stream.
///
///
/// Starting the stream causes data flow between the endpoint buffer and the audio engine. The first time this method is called,
/// the stream's audio clock position will be at 0. Otherwise, the clock resumes from its position at the time that the stream
/// was last paused with a call to Stop. Call Reset to reset the clock position to 0 and cause all active ISpatialAudioObject
/// instances to be revoked.
///
/// The stream must have been previously stopped with a call to Stop or the method will fail and return SPTLAUDCLNT_E_STREAM_NOT_STOPPED.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-start
// HRESULT Start();
new void Start();
/// Stops a running audio stream.
///
/// Stopping stream causes data to stop flowing between the endpoint buffer and the audio engine. You can consider this
/// operation to pause the stream because it leaves the stream's audio clock at its current stream position and does not reset
/// it to 0. A subsequent call to Start causes the stream to resume running from the current position. Call Reset to reset the
/// clock position to 0 and cause all active ISpatialAudioObject instances to be revoked.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-stop
// HRESULT Stop();
new void Stop();
/// Reset a stopped audio stream.
///
///
/// Resetting the audio stream flushes all pending data and resets the audio clock stream position to 0. Resetting the stream
/// also causes all active ISpatialAudioObject instances to be revoked. A subsequent call to Start causes the stream to start
/// from 0 position.
///
/// The stream must have been previously stopped with a call to Stop or the method will fail and return SPTLAUDCLNT_E_STREAM_NOT_STOPPED.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-reset
// HRESULT Reset();
new void Reset();
///
/// Puts the system into the state where audio object data can be submitted for processing and the ISpatialAudioObject state can
/// be modified.
///
///
/// The number of dynamic audio objects that are available to be rendered for the current processing pass. All allocated static
/// audio objects can be rendered in every pass. For information on audio object types, see AudioObjectType.
///
/// The size, in audio frames, of the buffer returned by GetBuffer.
///
///
/// This method must be called each time the event passed in the SpatialAudioObjectRenderStreamActivationParams to
/// ISpatialAudioClient::ActivateSpatialAudioStream is signaled, even if there no audio object data to submit.
///
///
/// For each BeginUpdatingAudioObjects call, there should be a corresponding call to EndUpdatingAudioObjects call. If
/// BeginUpdatingAudioObjects is called twice without a call EndUpdatingAudioObjects between them, the second call
/// to BeginUpdatingAudioObjects will return SPTLAUDCLNT_E_OUT_OF_ORDER.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-beginupdatingaudioobjects
// HRESULT BeginUpdatingAudioObjects( UINT32 *availableDynamicObjectCount, UINT32 *frameCountPerBuffer );
new void BeginUpdatingAudioObjects(out uint availableDynamicObjectCount, out uint frameCountPerBuffer);
///
/// Notifies the system that the app has finished supplying audio data for the spatial audio objects activated with ActivateSpatialAudioObject.
///
/// The pointers retrieved with ISpatialAudioObjectBase::GetBuffer can no longer be used after this method is called.
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-endupdatingaudioobjects
// HRESULT EndUpdatingAudioObjects();
new void EndUpdatingAudioObjects();
/// Activates an ISpatialAudioObject for audio rendering.
///
/// The type of audio object to activate. For dynamic audio objects, this value must be AudioObjectType_Dynamic. For
/// static audio objects, specify one of the static audio channel values from the enumeration. Specifying
/// AudioObjectType_None will produce an audio object that is not spatialized.
///
/// Receives a pointer to the activated interface.
///
/// A dynamic ISpatialAudioObject is one that was activated by setting the type parameter to the
/// ActivateSpatialAudioObject method to AudioObjectType_Dynamic. The client has a limit of the maximum number of
/// dynamic spatial audio objects that can be activated at one time. After the limit has been reached, attempting to activate
/// additional audio objects will result in this method returning an SPTLAUDCLNT_E_NO_MORE_OBJECTS error. To avoid this, call
/// Release on each dynamic ISpatialAudioObject after it is no longer being used to free up the resource so that it can
/// be reallocated. See ISpatialAudioObject::IsActive and ISpatialAudioObject::SetEndOfStream for more information on the
/// managing the lifetime of spatial audio objects.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstream-activatespatialaudioobject
// HRESULT ActivateSpatialAudioObject( AudioObjectType type, ISpatialAudioObject **audioObject );
ISpatialAudioObject ActivateSpatialAudioObject([In] AudioObjectType type);
}
///
///
/// Base interface that provides methods for controlling a spatial audio object render stream, including starting, stopping, and
/// resetting the stream. Also provides methods for activating new ISpatialAudioObject instances and notifying the system when you
/// are beginning and ending the process of updating activated spatial audio objects and data.
///
///
/// This interface is a part of Windows Sonic, Microsoft’s audio platform for more immersive audio which includes integrated spatial
/// sound on Xbox and Windows.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nn-spatialaudioclient-ispatialaudioobjectrenderstreambase
[ComImport, Guid("FEAAF403-C1D8-450D-AA05-E0CCEE7502A8"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface ISpatialAudioObjectRenderStreamBase
{
/// Gets the number of dynamic spatial audio objects that are currently available.
/// The number of dynamic spatial audio objects that are currently available.
///
///
/// A dynamic ISpatialAudioObject is one that was activated by setting the type parameter to the ActivateSpatialAudioObject
/// method to AudioObjectType_Dynamic. The system has a limit of the maximum number of dynamic spatial audio objects that
/// can be activated at one time. Call Release on an ISpatialAudioObject when it is no longer being used to free up the
/// resource to create new dynamic spatial audio objects.
///
///
/// You should not call this method after streaming has started, as the value is already provided by
/// ISpatialAudioObjectRenderStreamBase::BeginUpdatingAudioObjects. This method should only be called before streaming has
/// started, which occurs after ISpatialAudioObjectRenderStreamBase::Start is called.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-getavailabledynamicobjectcount
// HRESULT GetAvailableDynamicObjectCount( UINT32 *value );
uint GetAvailableDynamicObjectCount();
/// Gets additional services from the ISpatialAudioObjectRenderStream.
///
/// The interface ID for the requested service. The client should set this parameter to one of the following REFIID values:
/// IID_IAudioClock
/// IID_IAudioClock2
/// IID_IAudioStreamVolume
///
///
/// Pointer to a pointer variable into which the method writes the address of an instance of the requested interface. Through
/// this method, the caller obtains a counted reference to the interface. The caller is responsible for releasing the interface,
/// when it is no longer needed, by calling the interface's Release method. If the GetService call fails, *ppv is NULL.
///
///
///
/// If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values
/// shown in the following table.
///
///
///
/// Return code
/// Description
///
/// -
/// E_POINTER
/// Parameter ppv is NULL.
///
/// -
/// SPTLAUDCLNT_E_DESTROYED
/// The ISpatialAudioClient associated with the spatial audio stream has been destroyed.
///
/// -
/// AUDCLNT_E_DEVICE_INVALIDATED
///
/// The audio endpoint device has been unplugged, or the audio hardware or associated hardware resources have been reconfigured,
/// disabled, removed, or otherwise made unavailable for use.
///
///
/// -
/// SPTLAUDCLNT_E_INTERNAL
/// An internal error has occurred.
///
/// -
/// AUDCLNT_E_UNSUPPORTED_FORMAT
/// The media associated with the spatial audio stream uses an unsupported format.
///
///
///
///
/// The GetService method supports the following service interfaces:
///
/// -
/// IAudioClock
///
/// -
/// IAudioClock2
///
/// -
/// IAudioStreamVolume
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-getservice
// HRESULT GetService( REFIID riid, void **service );
[PreserveSig]
HRESULT GetService(in Guid riid, [MarshalAs(UnmanagedType.IUnknown, IidParameterIndex = 0)] out object service);
/// Starts the spatial audio stream.
///
///
/// Starting the stream causes data flow between the endpoint buffer and the audio engine. The first time this method is called,
/// the stream's audio clock position will be at 0. Otherwise, the clock resumes from its position at the time that the stream
/// was last paused with a call to Stop. Call Reset to reset the clock position to 0 and cause all active ISpatialAudioObject
/// instances to be revoked.
///
/// The stream must have been previously stopped with a call to Stop or the method will fail and return SPTLAUDCLNT_E_STREAM_NOT_STOPPED.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-start
// HRESULT Start();
void Start();
/// Stops a running audio stream.
///
/// Stopping stream causes data to stop flowing between the endpoint buffer and the audio engine. You can consider this
/// operation to pause the stream because it leaves the stream's audio clock at its current stream position and does not reset
/// it to 0. A subsequent call to Start causes the stream to resume running from the current position. Call Reset to reset the
/// clock position to 0 and cause all active ISpatialAudioObject instances to be revoked.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-stop
// HRESULT Stop();
void Stop();
/// Reset a stopped audio stream.
///
///
/// Resetting the audio stream flushes all pending data and resets the audio clock stream position to 0. Resetting the stream
/// also causes all active ISpatialAudioObject instances to be revoked. A subsequent call to Start causes the stream to start
/// from 0 position.
///
/// The stream must have been previously stopped with a call to Stop or the method will fail and return SPTLAUDCLNT_E_STREAM_NOT_STOPPED.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-reset
// HRESULT Reset();
void Reset();
///
/// Puts the system into the state where audio object data can be submitted for processing and the ISpatialAudioObject state can
/// be modified.
///
///
/// The number of dynamic audio objects that are available to be rendered for the current processing pass. All allocated static
/// audio objects can be rendered in every pass. For information on audio object types, see AudioObjectType.
///
/// The size, in audio frames, of the buffer returned by GetBuffer.
///
///
/// This method must be called each time the event passed in the SpatialAudioObjectRenderStreamActivationParams to
/// ISpatialAudioClient::ActivateSpatialAudioStream is signaled, even if there no audio object data to submit.
///
///
/// For each BeginUpdatingAudioObjects call, there should be a corresponding call to EndUpdatingAudioObjects call. If
/// BeginUpdatingAudioObjects is called twice without a call EndUpdatingAudioObjects between them, the second call
/// to BeginUpdatingAudioObjects will return SPTLAUDCLNT_E_OUT_OF_ORDER.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-beginupdatingaudioobjects
// HRESULT BeginUpdatingAudioObjects( UINT32 *availableDynamicObjectCount, UINT32 *frameCountPerBuffer );
void BeginUpdatingAudioObjects(out uint availableDynamicObjectCount, out uint frameCountPerBuffer);
///
/// Notifies the system that the app has finished supplying audio data for the spatial audio objects activated with ActivateSpatialAudioObject.
///
/// The pointers retrieved with ISpatialAudioObjectBase::GetBuffer can no longer be used after this method is called.
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreambase-endupdatingaudioobjects
// HRESULT EndUpdatingAudioObjects();
void EndUpdatingAudioObjects();
}
///
/// Provides notifications for spatial audio clients to respond to changes in the state of an ISpatialAudioObjectRenderStream.
///
/// You register the object that implements this interface by assigning it to the NotifyObject parameter of the
/// SpatialAudioClientActivationParams structure passed into the ISpatialAudioClient::ActivateSpatialAudioStream method. After
/// registering its ISpatialAudioObjectRenderStreamNotify interface, the client receives event notifications in the form of
/// callbacks through the OnAvailableDynamicObjectCountChange method in the interface.
///
///
/// This interface is a part of Windows Sonic, Microsoft’s audio platform for more immersive audio which includes integrated spatial
/// sound on Xbox and Windows.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nn-spatialaudioclient-ispatialaudioobjectrenderstreamnotify
[PInvokeData("spatialaudioclient.h", MSDNShortId = "3729D985-9040-43AD-A8B0-045509FE2F20")]
[ComImport, Guid("DDDF83E6-68D7-4C70-883F-A1836AFB4A50"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface ISpatialAudioObjectRenderStreamNotify
{
///
/// Notifies the spatial audio client when the rendering capacity for an ISpatialAudioObjectRenderStream is about to change,
/// specifies the time after which the change will occur, and specifies the number of dynamic audio objects that will be
/// available after the change.
///
/// The spatial audio render stream for which the available dynamic object count is changing.
///
/// The time after which the spatial resource limit will change, in 100-nanosecond units. A value of 0 means that the change
/// will occur immediately.
///
///
/// The number of dynamic spatial audio objects that will be available to the stream after hnsComplianceDeadlineTime.
///
/// If the method succeeds, it returns S_OK. If it fails, it returns an error code.
///
///
/// A dynamic ISpatialAudioObject is one that was activated by setting the type parameter to the
/// ISpatialAudioObjectRenderStream::ActivateSpatialAudioObject method to AudioObjectType_Dynamic. The client has a limit
/// of the maximum number of dynamic spatial audio objects that can be activated at one time. When the capacity of the audio
/// rendering pipeline changes, the system will dynamically adjust the maximum number of concurrent dynamic spatial audio
/// objects. Before doing so, the system will call OnAvailableDynamicObjectCountChange to notify clients of the resource
/// limit change.
///
///
/// Call Release on an ISpatialAudioObject when it is no longer being used to free up the resource to create new dynamic
/// spatial audio objects.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/nf-spatialaudioclient-ispatialaudioobjectrenderstreamnotify-onavailabledynamicobjectcountchange
// HRESULT OnAvailableDynamicObjectCountChange( ISpatialAudioObjectRenderStreamBase *sender, LONGLONG hnsComplianceDeadlineTime,
// UINT32 availableDynamicObjectCountChange );
[PreserveSig]
HRESULT OnAvailableDynamicObjectCountChange([In] ISpatialAudioObjectRenderStreamBase sender, int hnsComplianceDeadlineTime, [In] uint availableDynamicObjectCountChange);
}
///
/// Represents optional activation parameters for a spatial audio render stream. Pass this structure to ActivateAudioInterfaceAsync
/// when activating an ISpatialAudioClient interface.
///
///
/// The following example code shows how to initialize this structure.
/// To access the ActivateAudioIntefaceAsync, you will need to link to mmdevapi.lib.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/ns-spatialaudioclient-spatialaudioclientactivationparams
// typedef struct SpatialAudioClientActivationParams { GUID tracingContextId; GUID appId; int majorVersion; int minorVersion1; int
// minorVersion2; int minorVersion3; } SpatialAudioClientActivationParams;
[PInvokeData("spatialaudioclient.h", MSDNShortId = "6FEC7A70-D12E-4DB9-91DC-A54D5CCF8B57")]
[StructLayout(LayoutKind.Sequential)]
public struct SpatialAudioClientActivationParams
{
/// An app-defined context identifier, used for event logging.
public Guid tracingContextId;
///
/// An identifier for the client app, used for event logging.
/// majorVersion
/// The major version number of the client app, used for event logging.
/// minorVersion1
/// The first minor version number of the client app, used for event logging.
/// minorVersion2
/// The second minor version number of the client app, used for event logging.
/// ####### minorVersion3
/// The third minor version number of the client app, used for event logging.
///
public Guid appId;
///
public int majorVersion;
///
public int minorVersion1;
///
public int minorVersion2;
///
public int minorVersion3;
}
///
/// Represents activation parameters for a spatial audio render stream. Pass this structure to
/// ISpatialAudioClient::ActivateSpatialAudioStream when activating a stream.
///
// https://docs.microsoft.com/en-us/windows/win32/api/spatialaudioclient/ns-spatialaudioclient-spatialaudioobjectrenderstreamactivationparams
// typedef struct SpatialAudioObjectRenderStreamActivationParams { const WAVEFORMATEX *ObjectFormat; AudioObjectType
// StaticObjectTypeMask; UINT32 MinDynamicObjectCount; UINT32 MaxDynamicObjectCount; AUDIO_STREAM_CATEGORY Category; HANDLE
// EventHandle; ISpatialAudioObjectRenderStreamNotify *NotifyObject; } SpatialAudioObjectRenderStreamActivationParams;
[PInvokeData("spatialaudioclient.h", MSDNShortId = "DD27FDE1-3B4B-4C11-A980-15AF60A3A75B")]
[StructLayout(LayoutKind.Sequential)]
public struct SpatialAudioObjectRenderStreamActivationParams
{
///
/// Format descriptor for a single spatial audio object. All objects used by the stream must have the same format and the format
/// must be of type WAVEFORMATEX or WAVEFORMATEXTENSIBLE.
///
public IntPtr ObjectFormat;
///
/// A bitwise combination of AudioObjectType values indicating the set of static spatial audio channels that will be
/// allowed by the activated stream.
///
public AudioObjectType StaticObjectTypeMask;
///
/// The minimum number of concurrent dynamic objects. If this number of dynamic audio objects can't be activated simultaneously,
/// ISpatialAudioClient::ActivateSpatialAudioStream will fail with this error SPTLAUDCLNT_E_NO_MORE_OBJECTS.
///
public uint MinDynamicObjectCount;
/// The maximum number of concurrent dynamic objects that can be activated with ISpatialAudioObjectRenderStream.
public uint MaxDynamicObjectCount;
/// The category of the audio stream and its spatial audio objects.
public AUDIO_STREAM_CATEGORY Category;
///
/// The event that will signal the client to provide more audio data. This handle will be duplicated internally before it is used.
///
public HANDLE EventHandle;
///
/// The object that provides notifications for spatial audio clients to respond to changes in the state of an
/// ISpatialAudioObjectRenderStream. This object is used to notify clients that the number of dynamic spatial audio objects that
/// can be activated concurrently is about to change.
///
public ISpatialAudioObjectRenderStreamNotify NotifyObject;
}
}
}