Saving Codec Properties

This chapter shows you how to handle codecs and how to save and load the properties of a codec.

Introduction

The source code for this sample program can be found under samples\C# *\Saving Codec Properties in your My Documents/IC Imaging Control 3.5 directory.

A codec compresses and decompresses video streams. Sometimes, a codec is also referred to as a "compressor" or an "avicompressor".

The properties of some (but not all) codecs can be retrieved and assigned with IC Imaging Control. For example, the quality of a video stream may be set before it is saved.

Codec properties are supplied as a binary data stream. It is very important to know the length of the data stream, as later when an application loads the data stream, it is required to allocate memory for it.

The saving file format must be binary, because the data stream is also binary.

You should not alter the binary data stream from a codec. Doing so would make the data no longer fit the codec, thus causing unpredictable errors. Furthermore, the codec properties of one codec will not match each other. IC Imaging Control prevents this situation from happening at all - it causes an error message.

A codec is an external DLL file that is handled by an AviCompressor object. If an AviCompressor object becomes invalid, the DLL will be removed from memory. In this case, most codecs will loose their previously set properties. You should, therefore, declare a global AviCompressor object in your form in order to avoid loosing properties.

You can retrieve data from or assign data to codecs where the property PropertyPageAvailable is True. It is therefore necessary to check this property before performing an operation.

Setting up the Project

Create a new project and add IC Imaging Control to the form. Now add 3 buttons to the form and label them Save Data, Load Data and Show Property Page. Name the buttons cmdSaveData, cmdLoadData and cmdShowPropertyPage respectively. Add at least one combo box to the form and name it cboVideoCodec. This combo box will contain the names of the codecs.

Setting Up the Codec

First of all, an application needs a global AviCompressor object that contains the data of the codec. This must be global, because the AviCompressor 's properties will be lost when it is removed from memory. So add the following line to the beginning of the form:

[C#]
private TIS.Imaging.AviCompressor _selectedCodec;

Add a Form_Load event procedure to the form and enter the following code to fill the combo box with the available codecs:

[C#]
private void Form1_Load(object sender, EventArgs e)
{
    // Insert all installed codecs into the cboVideoCodec combobox.
    foreach (TIS.Imaging.AviCompressor codec in TIS.Imaging.AviCompressor.AviCompressors)
    {
        cboVideoCodec.Items.Add(codec);
    }
    // Show the first codec in the combobox.
    cboVideoCodec.SelectedIndex = 0;
    _selectedCodec = (TIS.Imaging.AviCompressor)cboVideoCodec.SelectedItem;
    // Enable or disable the buttons.
    cmdShowPropertyPage.Enabled = _selectedCodec.PropertyPageAvailable;
    cmdLoadData.Enabled = _selectedCodec.PropertyPageAvailable;
    cmdSaveData.Enabled = _selectedCodec.PropertyPageAvailable;
}

This code uses the AviCompressor.AviCompressors property to fetch a list of all available codecs. As you can see, the global variable Codec is used as item in the For Each .. In .. statement. The first available codec will be assigned to the global AviCompressor object Codec. The three buttons will be enabled or disabled according to the property PropertyPageAvailable in the AviCompressor object. This avoids performing operations that are not supported by the codec.

Now add the Click event procedure of the combo box cboVideoCodec to your form:

Now add the SelectedValueChanged event procedure of the combo box cboVideoCodec to your form:

[C#]
private void cboVideoCodec_SelectedIndexChanged(object sender, EventArgs e)
{
    _selectedCodec = (TIS.Imaging.AviCompressor)cboVideoCodec.SelectedItem;
    // Enable or disable the buttons.
    cmdShowPropertyPage.Enabled = _selectedCodec.PropertyPageAvailable;
    cmdLoadData.Enabled = _selectedCodec.PropertyPageAvailable;
    cmdSaveData.Enabled = _selectedCodec.PropertyPageAvailable;
}

The selected item of the combo box refers to an AviCompressor object. This item is assigned to the global AviCompressor object Codec.

The AviCompressor 's property PropertyPageAvailable is used to disable or enable the buttons. This prevents, for example, the user from pressing the cmdShowPropertyPage button when no property dialog is available for the codec.

Now, add the Click event procedure of the cmdShowPropertyPage button to your form:

[C#]
private void cmdShowPropertyPage_Click(object sender, EventArgs e)
{
    _selectedCodec.ShowPropertyPage();
}

This shows the property dialog of the codec. The cmdShowPropertyPage button was enabled or disabled in the Form_Load and SelectedValueChanged event procedure, thus you do not need to check PropertyPageAvailable again.

Saving the Codec Properties

As described above, the codec properties are supplied as a binary data stream. A binary data stream is simply a list of bytes. It is recommended to save the byte count in the data stream as the first element in the file. Using this first element, when the data is loaded from file, a dynamic array can be sized or resized to the matching byte count in order to accommodate the data.

Add the Click event procedure of cmdSaveData to your form:

[C#]
private void cmdSaveData_Click(object sender, EventArgs e)
{
    try
    {
        System.IO.FileStream filestream = new System.IO.FileStream("test.bin", System.IO.FileMode.Create, System.IO.FileAccess.Write);
        System.IO.BinaryWriter binWriter = new System.IO.BinaryWriter(filestream);
        binWriter.Write(_selectedCodec.Name);
        binWriter.Write(_selectedCodec.CompressorDataSize);
        binWriter.Write(_selectedCodec.CompressorData);
        binWriter.Close();
        filestream.Close();
    }
    catch (Exception Ex)
    {
        MessageBox.Show(Ex.Message);
    }
}

The codec properties will be saved in the file test.bin. Remember that the cmdSaveData button is only enabled, if AviCompressor.PropertyPageAvailable returns True. Alternatively, you can implement the following lines of code:

[C#]
if( Codec.PropertyPageAvailable )
{
    //  Do something like saving etc.
}
else
{
    MessageBox.Show( "This codec does not support properties!");
}

Loading the Codec Properties

Add the Click event procedure of cmdLoadData to your form:

[C#]
private void cmdLoadData_Click(object sender, EventArgs e)
{
    try
    {
        System.IO.FileStream filestream = new System.IO.FileStream("test.bin", System.IO.FileMode.Open, System.IO.FileAccess.Read);
        System.IO.BinaryReader binReader = new System.IO.BinaryReader(filestream);
        // Retrieve the name of the codec from the codec configuration file
        string codecName = binReader.ReadString();
        //Compare the codec name in the file with the current codec's name.
        if (_selectedCodec.Name == codecName)
        {
            // Read the length of the binary data.
            int codecDataLen = binReader.ReadInt32();
            // Assign the configuration data to the codec.
            _selectedCodec.CompressorData = binReader.ReadBytes(codecDataLen);
        }
        else
        {
            MessageBox.Show("The saved data does not match to the used codec.\n" +
                    "saved: " + codecName + "\n" +
                    "used: " + _selectedCodec.Name);
        }
        binReader.Close();
        filestream.Close();
    }
    catch (Exception Ex)
    {
        MessageBox.Show(Ex.Message);
    }
}

As described above at the cmdSaveData button, the cmdLoadData button is only enabled if AviCompressor.PropertyPageAvailable returns True. Before assigning data to a codec, you should check whether it supports properties:

[C#]
if( Codec.PropertyPageAvailable )
{
    //  Do something like loading etc.
}
else
{
    MessageBox.Show( "This codec does not support properties!");
}

Using the Codec for Capture

For the sake of completeness, we have included the following statement that shows how to use the codec to capture an AVI file see the Capturing an AVI File article:

<< Programmer's Guide