diff --git a/include/pa_win_wasapi.h b/include/pa_win_wasapi.h index bfc167a..1d86896 100644 --- a/include/pa_win_wasapi.h +++ b/include/pa_win_wasapi.h @@ -202,11 +202,13 @@ typedef struct PaWasapiJackDescription PaWasapiJackDescription; -/* Stream category. +/** Stream category. Note: - values are equal to WASAPI AUDIO_STREAM_CATEGORY enum - supported since Windows 8.0, noop on earler versions - values 1,2 are deprecated on Windows 10 and not included into enumeration + + @version Available as of 19.6.0 */ typedef enum PaWasapiStreamCategory { @@ -224,10 +226,12 @@ typedef enum PaWasapiStreamCategory PaWasapiStreamCategory; -/* Stream option. +/** Stream option. Note: - values are equal to WASAPI AUDCLNT_STREAMOPTIONS enum - supported since Windows 8.1, noop on earler versions + + @version Available as of 19.6.0 */ typedef enum PaWasapiStreamOption { @@ -247,7 +251,7 @@ typedef struct PaWasapiStreamInfo unsigned long flags; /**< collection of PaWasapiFlags */ - /* Support for WAVEFORMATEXTENSIBLE channel masks. If flags contains + /** Support for WAVEFORMATEXTENSIBLE channel masks. If flags contains paWinWasapiUseChannelMask this allows you to specify which speakers to address in a multichannel stream. Constants for channelMask are specified in pa_win_waveformat.h. Will be used only if @@ -255,7 +259,7 @@ typedef struct PaWasapiStreamInfo */ PaWinWaveFormatChannelMask channelMask; - /* Delivers raw data to callback obtained from GetBuffer() methods skipping + /** Delivers raw data to callback obtained from GetBuffer() methods skipping internal PortAudio processing inventory completely. userData parameter will be the same that was passed to Pa_OpenStream method. Will be used only if paWinWasapiRedirectHostProcessor flag is specified. @@ -263,7 +267,7 @@ typedef struct PaWasapiStreamInfo PaWasapiHostProcessorCallback hostProcessorOutput; PaWasapiHostProcessorCallback hostProcessorInput; - /* Specifies thread priority explicitly. Will be used only if paWinWasapiThreadPriority flag + /** Specifies thread priority explicitly. Will be used only if paWinWasapiThreadPriority flag is specified. Please note, if Input/Output streams are opened simultaniously (Full-Duplex mode) @@ -272,10 +276,16 @@ typedef struct PaWasapiStreamInfo */ PaWasapiThreadPriority threadPriority; - /* Stream category. */ + /** Stream category. + @see PaWasapiStreamCategory + @version Available as of 19.6.0 + */ PaWasapiStreamCategory streamCategory; - /* Stream option. */ + /** Stream option. + @see PaWasapiStreamOption + @version Available as of 19.6.0 + */ PaWasapiStreamOption streamOption; } PaWasapiStreamInfo; diff --git a/include/pa_win_wdmks.h b/include/pa_win_wdmks.h index 9a08c8f..3592962 100644 --- a/include/pa_win_wdmks.h +++ b/include/pa_win_wdmks.h @@ -53,14 +53,20 @@ extern "C" { #endif /* __cplusplus */ - /* Setup flags */ + /** Flags to indicate valid fields in PaWinWDMKSInfo. + @see PaWinWDMKSInfo + @version Available as of 19.5.0. + */ typedef enum PaWinWDMKSFlags { - /* Makes WDMKS use the supplied latency figures instead of relying on the frame size reported - by the WaveCyclic device. Use at own risk! */ + /** Makes WDMKS use the supplied latency figures instead of relying on the frame size reported + by the WaveCyclic device. Use at own risk! + */ paWinWDMKSOverrideFramesize = (1 << 0), - /* Makes WDMKS (output stream) use the given channelMask instead of the default */ + /** Makes WDMKS (output stream) use the given channelMask instead of the default. + @version Available as of 19.5.0. + */ paWinWDMKSUseGivenChannelMask = (1 << 1), } PaWinWDMKSFlags; @@ -69,11 +75,20 @@ extern "C" unsigned long size; /**< sizeof(PaWinWDMKSInfo) */ PaHostApiTypeId hostApiType; /**< paWDMKS */ unsigned long version; /**< 1 */ + + /** Flags indicate which fields are valid. + @see PaWinWDMKSFlags + @version Available as of 19.5.0. + */ unsigned long flags; - /* The number of packets to use for WaveCyclic devices, range is [2, 8]. Set to zero for default value of 2. */ + /** The number of packets to use for WaveCyclic devices, range is [2, 8]. Set to zero for default value of 2. */ unsigned noOfPackets; - /* If paWinWDMKSUseGivenChannelMask bit is set in flags, use this as channelMask instead of default */ + + /** If paWinWDMKSUseGivenChannelMask bit is set in flags, use this as channelMask instead of default. + @see PaWinWDMKSFlags + @version Available as of 19.5.0. + */ unsigned channelMask; } PaWinWDMKSInfo; diff --git a/include/portaudio.h b/include/portaudio.h index 0d4ad28..8a94aaf 100644 --- a/include/portaudio.h +++ b/include/portaudio.h @@ -51,52 +51,69 @@ extern "C" #endif /* __cplusplus */ /** Retrieve the release number of the currently running PortAudio build. - * For example, for version "19.5.1" this will return 0x00130501. - */ + For example, for version "19.5.1" this will return 0x00130501. + + @see paMakeVersionNumber +*/ int Pa_GetVersion( void ); /** Retrieve a textual description of the current PortAudio build, - * e.g. "PortAudio V19.5.0-devel, revision 1952M". - * The format of the text may change in the future. Do not try to parse the - * returned string. - * @deprecated use PaVersionInfo() instead - */ + e.g. "PortAudio V19.5.0-devel, revision 1952M". + The format of the text may change in the future. Do not try to parse the + returned string. + + @deprecated As of 19.5.0, use Pa_GetVersionInfo()->versionText instead. +*/ const char* Pa_GetVersionText( void ); /** - * Generate a packed integer version number in the same format used - * by Pa_GetVersion(). Use this to compare a specified version number with - * the currently running version. For example: - * - * if( Pa_GetVersion() < paMakeVersionNumber(19,5,1) ) {} - */ + Generate a packed integer version number in the same format used + by Pa_GetVersion(). Use this to compare a specified version number with + the currently running version. For example: + + @code + if( Pa_GetVersion() < paMakeVersionNumber(19,5,1) ) {} + @endcode + + @see Pa_GetVersion, Pa_GetVersionInfo + @version Available as of 19.5.0. +*/ #define paMakeVersionNumber(major, minor, subminor) \ (((major)&0xFF)<<16 | ((minor)&0xFF)<<8 | ((subminor)&0xFF)) /** - * A structure containing the components of the version numbers. - */ + A structure containing PortAudio API version information. + @see Pa_GetVersionInfo, paMakeVersionNumber + @version Available as of 19.5.0. +*/ typedef struct PaVersionInfo { int versionMajor; int versionMinor; int versionSubMinor; /** - * This is currently the Git revision hash but may change in the future. - * The versionControlRevision is updated by running a script before compiling the library. - * If the update does not occur, this value may refer to an earlier revision. - */ + This is currently the Git revision hash but may change in the future. + The versionControlRevision is updated by running a script before compiling the library. + If the update does not occur, this value may refer to an earlier revision. + */ const char *versionControlRevision; /** Version as a string, for example "PortAudio V19.5.0-devel, revision 1952M" */ const char *versionText; } PaVersionInfo; -/** - * The structure that this points to is statically allocated. - * Do not attempt to free it or modify it. - */ +/** Retrieve version information for the currently running PortAudio build. + @return A pointer to an immutable PaVersionInfo structure. + + @note This function can be called at any time. It does not require PortAudio + to be initialized. The structure pointed to is statically allocated. Do not + attempt to free it or modify it. + + @see PaVersionInfo, paMakeVersionNumber + @version Available as of 19.5.0. +*/ const PaVersionInfo* Pa_GetVersionInfo(); + /** Error codes returned by PortAudio functions. Note that with the exception of paNoError, all PaErrorCodes are negative. */