BASS.NET API for the Un4seen BASS Audio LibraryBassEncBASS_Encode_GetACMFormat Method (Int32, IntPtr, Int32, String, BASSACMFormat)BASS.NET API for the Un4seen BASS Audio Library
Presents the user with a list of available ACM (Audio Compression Manager) codec output formats to choose from.

The overload implements the Unicode version for the title, so the BASS_UNICODE flag will be added automatically.

Namespace: Un4seen.Bass.AddOn.Enc
Assembly: Bass.Net (in Bass.Net.dll) Version: 2.4.12.0
Syntax

public static int BASS_Encode_GetACMFormat(
	int handle,
	IntPtr form,
	int fromlen,
	string title,
	BASSACMFormat flags
)

Parameters

handle
Type: SystemInt32
The channel handle... a HSTREAM, HMUSIC, or HRECORD.
form
Type: SystemIntPtr
Pointer to the format buffer.
fromlen
Type: SystemInt32
Size of the format buffer. If this is 0, then a suggested format buffer length is returned (which is the maximum length of all installed codecs), without displaying the codec selector.
title
Type: SystemString
Window title for the selector... = "Choose the output format".
flags
Type: Un4seen.Bass.AddOn.EncBASSACMFormat
A combination of these flags BASSACMFormat:
BASS_ACM_DEFAULTUse the format buffer (form) contents as the default choice in the codec selector.
BASS_ACM_RATEOnly include formats with the same sample rate as the source.
BASS_ACM_CHANSOnly include formats with the same number of channels (mono/stereo) as the source.
BASS_ACM_SUGGESTSuggest a format without letting the user choose. The wanted format tag (eg. WAVE_FORMAT_ADPCM) should be specified in the HIWORD.
The HighWord - use MakeLong(Int16, Int16)(flags,format) - can be used to restrict the choice to a particular format tag (eg. WAVE_FORMAT_ADPCM). This is required with BASS_ACM_SUGGEST, and is optional otherwise. See WAVEFormatTag for a list of typical formats being used.

Return Value

Type: Int32
If successful, the user-selected codec format details are put in the provided buffer and the length of the format details is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code. If formlen is 0, then the suggested format buffer size is returned.
Remarks

This function presents the user with a list of available ACM codecs to choose from, given the sample format of the channel. The details of the chosen codec's output are returned in the form buffer, which can then be used with BASS_Encode_StartACM(Int32, ACMFORMAT, BASSEncode, ENCODEPROC, IntPtr) or BASS_Encode_StartACMFile(Int32, IntPtr, BASSEncode, String) to begin encoding.

The form buffer contents are actually a WAVEFORMATEX or ACMFORMAT structure. If writing the encoder output to a WAVE file, the form buffer contents would be the format chunk ("fmt") of the file.

To not let the user choose a codec, but automatically suggest a codec you might also use the BASS_Encode_GetACMFormatSuggest(Int32, BASSACMFormat, WAVEFormatTag) method.

ERROR CODEDescription
BASS_ERROR_HANDLEhandle is not valid.
BASS_ERROR_NOTAVAILThere are no codecs available that will accept the channel's format.
BASS_ERROR_ACM_CANCELThe user pressed the "cancel" button.
BASS_ERROR_UNKNOWNSome other mystery problem!

Examples

Let the user choose a codec, and setup an encoder on a channel using the chosen codec:
VB
' get suggested (maximum) format buffer size
Dim formlen As Integer = BassEnc.BASS_Encode_GetACMFormat(0, IntPtr.Zero, 0, Nothing, BASSACMFormat.BASS_ACM_NONE)
' create a buffer for the codec
Dim buffer(formlen - 1) As Byte
' now create a pinned handle, so that the Garbage Collector will not move this object
Dim hGC As GCHandle = GCHandle.Alloc(buffer, GCHandleType.Pinned)
' get the pointer to that pinned object
Dim codec As IntPtr = hGC.AddrOfPinnedObject()
' let the user choose a codec...
If BassEnc.BASS_Encode_GetACMFormat(channel, codec, formlen, "Choose your format", 
           BASSACMFormat.BASS_ACM_DEFAULT) > 0 Then
  ' get the generic codec information back
  Dim acm As ACMFORMAT = CType(Marshal.PtrToStructure(codec, GetType(ACMFORMAT)), ACMFORMAT)
  ' begin encoding using the codec
  BassEnc.BASS_Encode_StartACMFile(channel, codec, BASSEncode.BASS_ENCODE_DEFAULT, "acm.wav")
End If
' free the codec format buffer (you might free it even if encoding is still running)
hGC.Free()
// get suggested (maximum) format buffer size
int formlen = BassEnc.BASS_Encode_GetACMFormat(0, IntPtr.Zero, 0, null, BASSACMFormat.BASS_ACM_NONE);
// create a buffer for the codec
byte[] buffer = new byte[formlen];
// now create a pinned handle, so that the Garbage Collector will not move this object
GCHandle hGC = GCHandle.Alloc( buffer, GCHandleType.Pinned );
// get the pointer to that pinned object
IntPtr codec = hGC.AddrOfPinnedObject();
// let the user choose a codec...
if ( BassEnc.BASS_Encode_GetACMFormat( channel, codec, formlen, "Choose your format", BASSACMFormat.BASS_ACM_DEFAULT) > 0 )
{
  // get the generic codec information back
  ACMFORMAT acm = (ACMFORMAT)Marshal.PtrToStructure(codec, typeof(ACMFORMAT));
  // begin encoding using the codec
  BassEnc.BASS_Encode_StartACMFile( channel, codec, BASSEncode.BASS_ENCODE_DEFAULT, "acm.wav");
}
// free the codec format buffer (you might free it even if encoding is still running)
hGC.Free();
If you are into C# using native pointers in an unsafe codeblock would be even faster:
// get suggested (maximum) format buffer size
int formlen = BassEnc.BASS_Encode_GetACMFormat(0, IntPtr.Zero, 0, null, BASSACMFormat.BASS_ACM_NONE);
// create a buffer for the codec
byte[] buffer = new byte[formlen];
unsafe
{
  fixed (byte* p = buffer)
  {
    // let the user choose a codec...
    if ( BassEnc.BASS_Encode_GetACMFormat( channel, (IntPtr)p, formlen, "Choose your format", BASSACMFormat.BASS_ACM_DEFAULT) > 0 )
    {
      // get the generic codec information back
      ACMFORMAT acm = (ACMFORMAT)Marshal.PtrToStructure((IntPtr)p, typeof(ACMFORMAT));
      // begin encoding using the codec
      BassEnc.BASS_Encode_StartACMFile( channel, acm, BASSEncode.BASS_ENCODE_DEFAULT, "acm.wav");
    }
  }
}
For more convenience use the other overload of BASS_Encode_GetACMFormat(Int32, IntPtr, Int32, String, BASSACMFormat).
See Also

Reference