MXFLib Documentation

1

Introduction

This is the Open Source MXF Library "MXFLib" please see the following license

MXFLib License

Copyright (c) 2002-2007, Matt Beard, BBC R&D and Metaglue Corporation

This software is provided 'as-is', without any express or implied warranty.
In no event will the authors be held liable for any damages arising from
the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must
     not claim that you wrote the original software. If you use this
     software in a product, an acknowledgment in the product
     documentation would be appreciated but is not required.

  2. Altered source versions must be plainly marked as such, and must
     not be misrepresented as being the original software.

  3. This notice may not be removed or altered from any source
     distribution.

A Note About Smart Pointers

Memory management is simplified as much as possible by using smart pointers. These handle deletion of objects once the last referring pointer is deleted (or changed so that it no longer points to the object).

A few things should to be noted about these pointers:

• Most MXFlib classes have smart pointers defined with the name of the class followed by "Ptr".
• De-referencing by -> works as you would expect. Access using "." gives properties of the pointer, not the referenced object.
• They are generally safe as long as they are set from the result of "new". Don't set from the address of an object, especially if it is not allocated using "new".
• Don't mix normal pointers and smart pointers, if you need to use a pointer use a smart pointer if one exists for that class.
• If you make a class and want to use smart pointers to it derive the class from RefCount<YourClass>. This makes it safer to mix normal pointers and smart pointers (by ensuring a consistent reference count) but it doesn't stop objects being deleted with some standard pointers still referencing it.
• Smart pointers can be set to NULL (and start that way when built).
• You cannot say "if (Ptr == NULL)" because the compiler doesn't know whether to compare the pointer value of Ptr with "NULL" or build a smart pointer from "NULL" and compare it with Ptr. Use "if (!Ptr)" instead.

Notes about operator functions and SmartPointers:

• SmartPtr::operator== is defined to give true if both pointers reference the same object. != works in much the same way.
• SmartPtr::operator< is defined to compare the referenced objects not the pointers. This allows smart pointers to be used in maps.
• Some smart pointers in MXFlib add extra "operator" functions that access the referenced objects to make life simpler. For example the following are all equivalent for the MDObjectPtr "Preface":

      Ver = Preface["Version"];
      Ver = Preface->operator[]("Version");
      Ver = Preface->Child("Version");
  

Polymorphic Smart Pointers

Smart pointers can be used as polymorphic pointers, however:

• The base class must be derived from RefCount<the-base-class>
  • No derived class can also be derived from a form of RefCount<>
  • The base class must define a virtual destructor
• Member functions and properties not present in the base class must be accessed via the SmartPtr_Cast() macro as follows:

    class MyBase : public RefCount<MyBase> 
    {
        public: virtual int Func(void);    // Function available in all these types
        ...
    };
  
    class MyDerived
    {
        public: int Func(void);            // Local version of "Func()"
                int AdvancedFunc(void);    // Special available only to this type
    };
  
    typedef MyBasePtr SmartPtr<MyBase>;
  
    MyBasePtr Special = new MyDerived();
  
    int i = Special->Func();               // Can be accessed normally as it exists on the base class
    int j = SmartPtr_Cast(Special, MyDerived)->AdvancedFunc();
                                           // Requires casting as it doesn't exist on the base class
  

The Main Classes

MDObject - A metadata object.

Each item of header metadata is held in an MDObject. Each MDObject has a Type which is a pointer to an MDOType object. Each MDObject also has a Value which is a pointer to an MDValue object holding the actual value of the metadata object. MDObjects may contain child objects (for example the object could be a set or a pack). The mechanism by which children are contained is that MDObject is derived from MDObjectNamedList.

Note:

There are a number of classes that are conceptually derived from MDObject, however to allow smart pointers to be used they are actually derived from the class ObjectInterface and so hold a property of type MDObjectPtr called Object which can be accessed using functions of the same name as for an MDObject. For example class Partition is derived from ObjectInterface and so the following two commands produce the same result:

    Ver = ThisPartition->Object->GetUint("MajorVersion");
    Ver = ThisPartition->GetUint("MajorVersion");

MDValue - A metadata value.

MDValue objects provide type handling. Each MDValue object has a Type which is a pointer to an MDType object. Each MDObject can contain an actual value, or a set of children that make up the value (such as where the value is an array or a compound). The mechanism by which children are contained is that MDValue is derived from MDValueMap.

MDFile - An MXF file.

The MDFile class provides file access. When the file is opened a check is made for a run-in and if found all seeks are adjusted so that location 0 is the first byte after the run-in. Each MXFFile contains a RIP object called FileRIP.

Note:

It is planned that code will be added to cope with "discontinuities" in an MXF file. This means that if a chunk of data is missing from an MXF file it should be possible to read the rest of the file properly even though seeks to later parts of the file will need to be adjusted. It should also be possible to add some abstraction to allow a "middle part" of a file to be read safely, and without any special handling in the application, as long as at least one complete header metadata repetition exists. This means that any essence access code will have to be able to return a condition of "essence missing".

RIP - A Random Index Pack.

Provides an index of all (known) partitions in a file. Each partition in a RIP object has a BodySID, a ByteOffset and a smart pointer to a Partition object.

Note:

The pointer to the partition may be NULL if the partition is known about, but not available in memory (for example if the RIP has been read from an actual random index pack in the file). It is also possible for the BodySID and ByteOffset to be unknown if a partition is being built in memory. It is probably not valid for all three to be unknown.

Partition - Object holding data relating to a partition.

This class is derived from ObjectInterface, it holds extra items including a list of pointers to all metadata objects in the partition's header metadata, AllMetadata, and of only those items that are "top-level" (i.e. not referenced from other sets) TopLevelMetadata. Partitions have functions for manipulating partition specifics, such as ReadMetadata() and ReadIndex().

High Level Classes

Most of the classes are derived from ObjectInterface.

Note:

These classes are currently only supported when writing an MXF file they are not yet created when a file is read.

Metadata

This class holds data about a set of Header Metadata and encapsulates an MDObject holding the Preface set. The Metadata class includes functions for manipulating Packages.

Package

This class holds data about a Package (either a Mource Package or a Source Package). The Package class includes functions for manipulating Tracks.

Track

This class holds data about a Track. The Track class hides detail about the segment and includes functions for manipulating SourceClips and TimecodeComponents.

SourceClip

This class holds data about a SourceClip.

TimecodeComponent

This class holds data about a Timecode Component.

Here Be Dragons

In earlier times when explorers were mapping areas that they had discovered they would sometimes have a large unexplored area that for some reason they just didn't want to investigate. To explain the lack of any detail they would just write "Here be Dragons" on that area. People reading the map would stay clear until some mad fool was brave enough to go in and sort out what was really there.

In modern times programmers often come across scary areas that they don't want to deal with at this point (although they do need exploring later) and if they are nice they will warn people. In this code the word "DRAGONS" is used to flag an area where dangers lurk and brave programmers are sought to go and slay them before they wreak havoc on the whole project!

Actually the "Here Be Dragons" thing is nearly as much of a myth as drogons themselves. For more details see this article

An interesting use of "Here Be Dragons" in teaching C++

Still To Do...

• Finish the code
• Finish the documentation

Contact Info

matt@beard.org

---