Save and load objects configurations

Use the IMPersist interface to save and load object configurations in MPlatform SDK. For supported MFormats objects, use IMFPersist.

The examples below use an existing MPlatform MMixerClass instance named m_objMixer and the MPLATFORMLib namespace. The persistence methods can also be used with the other objects listed below. The configuration contents depend on the object.

MPlatform:

MFileClass
MItemClass
MPlaylistClass
MLiveClass
MRendererClass
MElement
MMixerClass
MComposerClass
MWriterClass
MChromaKey
MChromaKey2

MFormats:

MChromaKey
MChromaKey2

Save

Save the full configuration to a string by passing null as the first argument:

string XML;
(m_objMixer as IMPersist).PersistSaveToString(null, out XML, "");

Or save it to an external file. Use a full path in an existing writable folder:

string configPath = @"C:\Configs\mixer.xml";
(m_objMixer as IMPersist).PersistSaveToFile(null, configPath, "");

For file encoding and other save parameters, see the IMPersist reference.

To save the mixer's scene collection instead of its full stream configuration, use "scenes" as the first argument. This selector does not identify a single scene by ID:

string results;
m_objMixer.PersistSaveToString("scenes", out results, "");

Load

Pass either an XML string or the full path to a configuration file to PersistLoad:

// Load the string saved above.
(m_objMixer as IMPersist).PersistLoad(null, XML, "");

// Alternatively, load the saved file.
(m_objMixer as IMPersist).PersistLoad(null, configPath, "");

For scene-only loading, use the same "scenes" selector:

m_objMixer.PersistLoad("scenes", results, "");

MMixer video and audio formats

A full MMixer configuration includes the configured video and audio conversion formats, together with its streams and scenes. Saving reads both formats with eMFormatType.eMFT_Convert; loading requests those conversion settings through FormatVideoSet and FormatAudioSet. Audio track-mask restoration has the limitation described below.

Configure the desired formats before saving, and read back the audio settings to check the actual track mask. For example:

M_VID_PROPS video = new M_VID_PROPS();
video.eVideoFormat = eMVideoFormat.eMVF_HD720_50p;
m_objMixer.FormatVideoSet(eMFormatType.eMFT_Convert, ref video);

M_AUD_PROPS audio = new M_AUD_PROPS();
audio.nChannels = 8;
audio.nSamplesPerSec = 44100;
audio.nBitsPerSample = 16;
audio.nTrackSplitBits = 0; // Does not guarantee clearing an existing mask.
m_objMixer.FormatAudioSet(eMFormatType.eMFT_Convert, ref audio);

M_AUD_PROPS configuredAudio;
int configuredAudioIndex;
string configuredAudioName;
m_objMixer.FormatAudioGet(eMFormatType.eMFT_Convert,
    out configuredAudio, out configuredAudioIndex, out configuredAudioName);
// Check configuredAudio.nTrackSplitBits against the required track layout.

string mixerXML;
m_objMixer.PersistSaveToString(null, out mixerXML, "");

For more about setting formats through IMFormat, see Converting source video and audio formats.

The format portion of a configuration can look like this. This excerpt omits the stream and scene configuration:

<m_config>
  <video video_format="HD720-50p" width="1280" rate="50.0"
         pixel_format="ARGB32" aspect_ratio="16:9" interlace="progressive" />
  <audio channels="8" rate="44100" bits="16" track_split="0" />
</m_config>

The following tables cover the attributes handled by MMixer's video and audio format persistence. These values are configurable settings, not read-only statistics. Set them through FormatVideoSet or FormatAudioSet, and retrieve the settings through the corresponding Get methods. Applying track_split depends on the current audio settings, as explained below. The XML attribute names below are not PropsSet property paths.

Video attributes

A named preset supplies its standard video parameters during loading. Custom formats use the explicit dimensions and frame rate. Saving may omit default or unspecified values, so this XML is not a copy of every field in M_VID_PROPS: row stride (nRowBytes) and GPU flags (eGPUFlags) are not persisted in this block.

For custom RGB formats, check the restored dimensions as well as the format name: a negative height is omitted by the saver.

Audio attributes

Track mask restoration

MMixer saves track_split and reads it during loading, but this does not guarantee that the loaded mask replaces the current value. If the channel count, sample rate, and bits per sample match the current audio format, a change to the track mask alone is not applied. For example, loading track_split="160" over an audio format with the same channel count, sample rate, and bits per sample and a current mask of 0 leaves the mask at 0.

Also, requesting nTrackSplitBits = 0, directly or through XML, can preserve an existing mask when the channel count matches. Do not rely on zero to clear track information. Read nTrackSplitBits after both FormatAudioSet and PersistLoad, and compare it with the track layout your application requires.

Read formats after loading

Read both conversion settings after PersistLoad. Use the returned video format and audio format name to refresh format selectors in your application. Check restoredAudio.nTrackSplitBits separately because loading can retain the previous mask:

m_objMixer.PersistLoad(null, mixerXML, "");

M_VID_PROPS restoredVideo;
M_AUD_PROPS restoredAudio;
int videoIndex, audioIndex;
string videoName, audioName;

m_objMixer.FormatVideoGet(eMFormatType.eMFT_Convert,
    out restoredVideo, out videoIndex, out videoName);
m_objMixer.FormatAudioGet(eMFormatType.eMFT_Convert,
    out restoredAudio, out audioIndex, out audioName);

// Check restoredAudio.nTrackSplitBits against the required track layout.
// Refresh UI controls from restoredVideo.eVideoFormat and audioName.
// For custom formats, also display the returned dimensions and frame rate.

These calls retrieve the configured conversion settings. To query the current output format, use eMFormatType.eMFT_Output.

Scene-only loading does not restore mixer formats. Loading with "scenes", or loading XML whose root is m_scenes, restores scenes without applying the video and audio format blocks, even if those blocks are present in the saved XML. Use full configuration loading when you need to restore formats too.

For older configurations without video or audio blocks, read the settings back after loading and explicitly apply the formats your application requires. Do not assume that every format setting made before loading will be retained.