ReleaseNotes.txt

AAF SDK v1.1.6
==============

2012-10-29

This SDK is the reference implementation of the Advanced
Authoring Format (AAF) version 1.1. See doc/aafeditprotocol.pdf,
doc/aafobjectspec-v1.1.pdf, doc/aafstoredformatspec-v1.0.1.pdf and
doc/aafcontainerspec-v1.0.1.pdf for the AAF specification documents.

Supported platforms
-------------------

This release has been tested on the following platforms:

  MacOS X 10.8.3 Intel (32 and 64 bit builds, 64-bit OS)
    (gcc 4.2.1 Apple build 5658)
  x86-Linux: 
    Centos 6.3 (32 bit, gcc 4.4.6 glibc 2.12 kernel 2.6)
  Windows 7/64
    Visual Studio 2008 (32 and 64 bit builds)
    Visual Studio 2010 (32 and 64 bit builds)

The release was not tested on the following platforms, however, these
were supported by the prior release and no changes in this release are
expected to affect them:

  Solaris 10 (gcc 4.3.3)
  MacOS X 10.6.8 Intel (32 and 64 bit builds, 64-bit OS)
    (xcode 4.0.2, gcc 4.2.1 Apple build 5666)
  MacOS X 10.5.8 PowerPC (Xcode 3.1.3, gcc 4.0.1 Apple build 5593)
  Windows 2000 SP4 32-bit (Microsoft Visual C++ 7.1)
  Windows XP SP2 32-bit (Microsoft Visual C++ 7.1, 8.0 and 9.0)
  x86-Linux: 
    Fedora 14 (gcc 4.5.1, glibc 2.13, kernel 2.6)
  x86_64-Linux:
    OpenSUSE 11.1 (gcc 4.3.2, glibc 2.9, kernel 2.6)

Licensing
---------

The source code of this SDK is licensed using the AAF Public Source
License version 2.0 (see LEGAL/AAFSDKPSL.TXT).

WARNING:  ALTHOUGH NO ADDITIONAL LICENSE IS REQUIRED FROM THE CONTRIBUTORS
TO USE THE SOURCE CODE IN THIS AAF SDK TO WHICH THE AAF PSL APPLIES,
THE AAF PSL DOES NOT PROVIDE ALL LICENSES, UNDER INTELLECTUAL
PROPERTY RIGHTS COVERING THE AAF STANDARD, THAT MAY BE NECESSARY TO
CREATE AND DISTRIBUTE AAF COMPLIANT PRODUCTS.  PLEASE CONTACT THE AAF
ASSOCIATION, INC. FOR MORE INFORMATION ABOUT ANY ADDITIONAL LICENSES
THAT MAY BE REQUIRED TO CREATE AND DISTRIBUTE AAF COMPLIANT PRODUCTS
(HTTP://WWW.AAFASSOCIATION.ORG/POLICIES).

Major Changes from v1.1.5 to v1.1.6
-----------------------------------

The 1.1.6 provides explicit support for the .isr file extension in the
AAF SDK.

The primary addition is the ComFileExtensionTest test program and the
ComFileExtDevUtilVerityTest.sh script.  These tests were added to
ensure that the AAF is, and remains, independent of the file extension
used to name AAF files. The script ensures that common development
utilities do not have any built in assumptions that may frustrate
developers that use something other than ".aaf" as the extension of
their structured storage encoded AAF files. Note, that no such
limitations were expected and none were found as part of the
verification process undertaken for 1.1.6. The tests ensure that no
such dependencies are created in the future, and provide a well known
place to test such limitations should any be detected in the future
that affect .isr developers.

These tests are now included in "make check" builds on unix platforms.
The ComFileExtensionTest is now part of the RunModTestAndExamples.bash
script used to test Microsoft Windows builds.

The com-api documentation for each of the functions defined in
AAFModule.dod that take a filename argument was modified to: i) bring
it up to date in general (it had never been updated to reflect the
addition of klv and xml support), ii) explicitly note the extension
independence file names, and iii) to clearly document that both .aaf
and .isr are common extensions used for structured storage encoded AAF
files.

The online SDK API documentation was updated as part of this
release. It may be found at following url:
http://aaf.sourceforge.net/docs/aafapiman/

Major Changes from v1.1.4 to v1.1.5
-----------------------------------

Addition of VS10 (Visual Studio 2010) support.

Addition of 64 bit build support for: VS9, VS10, and OSX.

The 1.1.5 source code changes are limited to minor modifications that
were necessary to correct compiler warnings related to the addition of
support for the platforms noted above.

Note that VS10 modifies the directory layout that has been used for
VS9 and prior.  VS10 now prefixes the build output paths with the
platform name, i.e. Win32 or x86_64. Prior to VS10 the results of the
most recent successful build, regardless of configuration (Debug or
Release), were always placed in a generic "bin" and "lib" directory
(e.g. AAFWinSDK/vs9/bin). VS10 support discontinues this pattern. The
build outputs are found only in
AAFWinSDK/vs10/{Win32,x86_64}/{Debug,Release}/...

Note that the VS9 x86_64 build support requires that the solution be
cleaned before changing between Win32 or x86_64 platforms.  This
restriction does not exist in VS10.

Major Changes from v1.1.3 to v1.1.4
-----------------------------------

Plugin codec changes:
  Added DV50, DVCPROHD and IMX codec functionality using ffmpeg library, if
    available. libdv no longer supported.
  VC3/DNxHD: CompressionID initialized correctly.

API changes:
  Removed IAAFSubDescriptor & IAAFEssenceDescriptor2 APIs
    (EssenceDescriptor::SubDescriptors property removed from built-in model as
    it was incorrectly declared with a static PID)
  Added calculation of Sequence::Length for prepend, insert & remove
    operations
  Fixed SourceMob::AppendEdgeCode
  Improved handling of AAF files without CodecDefs - iterate over codecs
    to find one capable of reading the essence using IsCompressionSupported()
    API of AAFEssenceCodec3.
  Extend AAFMasterMob interface to add AddMasterSlotWithSequence() - similar
    to AddMasterSlot but instead adds a Sequence and then adds the SourceClip
    into the sequence, achieving better MXF interoperability.

Example code:
  ExportDV and ImportDV extended to exercise all supported DV and IMX formats.
  Added ExportAS05Effects example for AS-05 Effects Protocol

Testing:
  Unit tests:
    CAAFSequenceTest: extended to check correct Sequence::Length calculation.
    CAAFTypeDefStreamTest: extended to test growing stream and stream size
      near KAG alignment grid boundary.
    CAAFSourceMobTest: extended to test AppendTimeCode and AppendEdgeCode
  Added UTF16StoredString test to exercise storing/reading of Unicode code points
    greater than U+FFFF
  Added test cases and sample AAF files to test handling of files with missing
    CodecDefs
  Enhanced nightly build script (nightly_cvs_build.pl)

AAF-XML:
  Updated tag names (OMSymbolspace.cpp) to track SMPTE Reg-XML specification
    draft.

Model:
  Added AS-05 Effects Protocol identifiers (OperationDefs, ParameterDefs)
  Added aafMobIDNew() function to generate valid SMPTE UMID MobIDs.
  Track changes in SMPTE metadictionary spreadsheet format

  Removed SubDescriptor class, EssenceDescriptor::SubDescriptors property
    and StrongReferenceVector type, as EssenceDescriptor::SubDescriptors property
    was incorrectly declared with a static PID).

Utilities:
  AAFDotInstanceMapper - show weak refs to DefinitionObjects as "->Name".

Misc:
  Update license to AAF SDK Public Source License version 2.0.


Major Changes from v1.1.2 to v1.1.3
-----------------------------------

Platforms:
  Added support for Microsoft Visual C++ 8.0 compiler
  Added support for Microsoft Visual C++ 9.0 compiler
    Note. MSVC 7.1, 8.0 & 9.0 each have a sub-directory under AAFWinSDK.
    This is a change to the previous support for MSVC 7.1.
  Added support for Microsoft Vista

Plugin codec changes:
  Added Avid DNxHD and SMPTE VC3 plugin codecs
    Note. As supplied, these AAF codecs provide wrapping capability.
    With an additional library, they can provide compress/decompress capability.
  Use MSVC project configuration to control linking with optional VC3 library
  Added IAAFEssenceDataStream2 for access to MXF Essence Element Key
  Added setting of MXF Essence Element Key in CDCI, JPEG, DNxHD & VC3 codecs
  Added simple fallback strategy to select which codec to use when reading essence
    from a file without a codec definition on its file descriptor.
  Correctly open AAF files containing internal VC3 essence with legacy ULs

Existing API changes:
  RGBADescriptor::PixelLayout and RGBADescriptor::PaletteLayout changed to
    accept both '0' and 0 as terminator.
  Change FileDescriptor's GetContainerFormat and GetCodecDef to check if
    the weak reference can be resolved before getting the referenced
    object.  MXF files may have references to container and codec
    definitions that are not present in the dictionary.


Memory usage:
  Fix memory leaks
  Reduce memory footprint
  Add MemoryLeakTest test
  
Utilities:
  AAFAnalyzer updated for use with AMWA registration website
  Updated AAFAnalyzer to build with updated AAFWinSDK/vs7 platform
  Added AAF-XML XSD generation stylesheets
  Moved CAAFBuiltinDefs.h from the public API in ref-impl/include to
    Utilities/Include to make it clear that it's only an example or utility.
  Replaced deprecated CAAFBuiltinDefs.h macro usage with COM API calls
  Fix writing past the end of string bug in aafembed

Documentation:
  Updated README.TXT to reflect updated AAFWinSDK/vs* structure


Major Changes from v1.1.1 to v1.1.2
-----------------------------------

New stored format support:
  AAF-KLV (create file with file kind = kAAFFileKind_AafKlvBinary)
  AAF-XML (create file with file kind = kAAFFileKind_AafXmlText)

See "AAF-KLV implementation issues" for more details.

The AAF-XML support is fully functional, however it should be regarded
as experimental, pending the completion of SMPTE standardisation of the
XML schema as SMPTE 2001 Reg-XML. When standardisation is complete, the
implementation in the AAF toolkit will be updated to match the published
SMPTE specification.

Extended APIs:
  IAAFAES3PCMDescriptor2, IAAFEssenceData2, IAAFEssenceDescriptor2,
  IAAFEventMobSlot2, IAAFFileDescriptor2,  IAAFTypeDefStreamEx,
  IAAFTypeDefStream3

New APIs:
  IAAFAES3PCMDescriptor, IAAFBWFImportDecriptor, IAAFCachePageAllocator,
  IAAFDataEssenceDescriptor, IAAFDescriptiveClip, IAAFDescriptiveObject,
  IAAFDiagnosticOutput, IAAFFileEncoding, IAAFKLVEssenceDataParameters,
  IAAFKLVStreamParameters, IAAFMPEGVideoDescriptor,
  IAAFMultipleDescriptor, IAAFPlainEssenceData, IAAFPlainStreamData,
  IAAFProgress, IAAFRIFFChunk, IAAFStreamAccess, IAAFSubDescriptor,
  EnumAAFFileDescriptors, EnumAAFFileEncodings, EnumAAFRIFFChunks,
  EnumAAFSubDescriptors

  see http://aaf.sourceforge.net/docs/aafapiman/

New built-in stored object class definitions:
  AES3PCMDescriptor, BWFImportDescriptor, DataEssenceDescriptor,
  DescriptiveClip, DescriptiveObject, MPEGVideoDescriptor,
  MultipleDescriptor, RIFFChunk, SubDescriptor

New built-in stored object property definitions:
  AES3PCMDescriptor::
    AuxBitsMode, BlockStartOffset, ChannelStatusMode, Emphasis,
    FixedChannelStatusData, FixedUserData, UserDataMode
  BWFImportDescriptor::
    BextCodingHistory, QltyBasicData, QltyCueSheet, QltyEndOfModulation,
    QltyFileSecurityReport, QltyFileSecurityWave, QltyOperatorComment,
    QltyQualityEvent, QltyQualityParameter, QltyStartOfModulation,
    UnknownBWFChunks
  DataEssenceDescriptor::DataEssenceCoding
  DescriptiveClip::SourceTrackIDs
  EssenceDescriptor::SubDescriptors
  EventMobSlot::EventSlotOrigin
  FileDescriptor::LinkedSlotID
  MPEGVideoDescriptor::
    BitRate, ClosedGOP, CodedContentScanning, ConstantBPictureCount, 
    IdenticalGOP, LowDelay, MaxBPictureCount, MaxGOP, ProfileAndLevel,
    SingleSequenceexamples/com-api/ImportVC3/raw.dnx
  MultipleDescriptor::FileDescriptors
  RIFFChunk::
    ChunkData, ChunkID, ChunkLength

Revise AAFMetaDict.xls to track SMPTE metadata registers
  Build-in agreed list of DefinitionObject Instances
    (ContainerDefinitions and DataDefinition).
  Extend headergen to create built-in Dictionary DefinitionObject
    Instances.

New stream access APIs:
  IAAFPlainStreamData and IAAFPlainEssenceData provide access to the
  value of the stream, independent of the stored format. For AAF-KLV,
  the existing AAF stream interfaces provide access to the entire MXF
  stream (that is, all KLVs in the stream including any trailing KLV
  Fill). See CAAFPlainStreamDataTest and CAAFPlainEssenceDataTest module
  tests for examples.

Plugin Codec changes:
  Updated JPEG codec to enhance compatibility with Avid products

New Examples:
  ExportJPEG, ImportJPEG
  Updates and additions to AxLib

New Utilities:
  aaffmtconv - Convert between structured storage and XML stored formats
  AAFAnalyzer - AAF file compliance analyzer tool (under development)
  MXFDump - Dump MXF files in excruciating detail

Enhanced Tests:
  - Add encoding switch to OpenExistingModify test
  - Add test of IAAFTypeDefVariableArray::GetElements() for arrays of
    non-objects (scalars)
  - Add MetaModelVerification to MakeSDKExamples project where COM tests reside
  - Changes to TypeDefRecord module test to test v1.1.1 behaviour
  - Refactor TypeDefRecord module test to separate GetValue() and
    GetStruct() type calls to improve level of testing across different
    storage formats
  - Fix WAVEDescriptor & AIFCDescriptor module tests to handle foreign
    endian files
  - Include additional tests in "make check"
  - Use known OperationCategoryType in module tests so InfoDumper &
    ComPropDirectDump dump OK
  - Change ComPropDirectDump/dumper to not exit when dumping ExtEnum
    properties with non-existant names
  - Addition of nightly build and test script which generates static web page
    results

Other Enhancements:
  - Improve methods used to register structured storage OMStoredObjectFactory
    implementations, and to declare the default for each encoding type. Restore
    Schemasoft implementation as default on Windows.
  - Refactor kAAFSignature_* from AAFFileKinds.h to ImplAAFFile.cpp to address
    bug on MacOS 10.4.9 gcc 4.0.1 in which kAAFSignature_Aaf512Binary was not
    correctly statically initialised before user code was executed.

Build Options:
  - Saving of Object Directory is now optional (compiler option
    OM_SAVEOBJECTDIRECTORY). On reading, Object Direcory is no longer
    required to be present.
  - Root object class ID can now be written as a SMPTE UL or as the
    legacy UUID (compiler option OM_WRITELEGACYROOTCLASSID). Both
    values are recognised when reading. Default is to use legacy
    UUID value, for backwards compatibility.

Portability:
  - MacOS X on Intel support added (i386Darwin AAF platform)
  - Removed requirement to have a structured storage library built
    into AAF library (make AAF_NO_STRUCTURED_STORAGE=1)
  - Byte order (little endian/big endian) is determined at run time not compile
    time
  - Initial support for g++ on WIN32 enabling MinGW apps to link to AAF
    static libs. AAFCOAPI.dll library must still be built with MSVC.
    Refactor makefiles to enable make driven MSVC++ build
  - Additional compiler warning clean-up:
    Fix gcc 4.2.x deprecated conversion from string constant warnings.
    Fix gcc 4.3 warning for missing declarations. In gcc 4.3 the C++ header
    dependencies have been cleaned up so code cannot rely on indirect inclusion.
  - Build MXFDump on i386Darwin and SparcSolaris
  - Dependency generation for AAFPLATFORM=UniversalDarwin


Major Changes from v1.1.0 to v1.1.1
-----------------------------------

This is a bug-fix release.  The following problems in V1.1.0 are fixed with
this release:

- Writing a file containing a Set or Array of Records using V1.1.0 might
  result in a file that is unreadable.  Attempting to open such a file with a
  debug version of the SDK library will result in an assertion failure.
  Attempting to open such a file with a release version of the SDK library
  has the potential to cause a heap corruption.


- SourceForge Bug ID #1188299:
  ImplAAFSourceReference::SetChannelIDs() does not work 
  ImplAAFSourceReference::SetChannelIDs() passes its numberElements parameter
  directly to _channelIDs.copyToBuffer(), which is expecting a byte count not
  a number of elements. As a result, nothing is set if you call
  IAAFSourceReference2::SetChannelIDs() with less than 4 channel IDs, etc.

  The fix appears to be to pass (numberElements * sizeof(aafUInt32)) 
  instead of numberElements

  This also applied to IAAFSourceReference2.


- SourceForge Bug ID #1188301:
  ImplAAFSourceReference::GetChannelIDs() does not work 
  As with ImplAAFSourceReference::SetChannelIDs(),
  ImplAAFSourceReference::GetChannelIDs() passes the number of elements when
  it should be passing a byte count. Specifically, it passes numberElements to
  _channelIDs.copyToBuffer() instead of (numberElements *sizeof(aafUInt32)). 

  This also applied to IAAFSourceReference2.


- The 6 new IAAFSourceReference2 APIs were tested.


- SourceForge Bug ID #1191791:
  LastModified property of Header not set on AAFFile->Save() 
  When Save() is called on an IAAFFile object, the LastModified property on
  the Header is not updated and is written as 0000-00-00-00-00-00
  (aafTimeStamp_t).
  This occurred in version 1.1.0 and 1.0.2 of the AAF SDK. 


- Add support for powerpc64-linux platform (Apple G5, IBM Power64, etc).
  Tested using Gentoo Linux 2005.0 on Apple G5.


- Added tests for: IAAFHeader, IAAFAuxiliaryDescriptor, IAAFComponent and
  IAAFDictionary


- doxygen formatting fixes for dodo files

Removed features:
  - Support for MS VC 6 has been dropped and all .dsp/.dsw files removed



Major Changes From v1.0.2 to v1.1.0
-----------------------------------

Extended APIs:
  IAAFMob2, IAAFCDCIDescriptor2, IAAFComponent2, AAFCompositionMob2,
  IAAFDictionary2, IAAFDigitalImageDescriptor2, IAAFHeader2, IAAFMasterMob2,
  IAAFRGBADescriptor2, IAAFSourceReference2, IAAFTimelineMobSlot2
  IAAFEssenceCodec2

  see http://aaf.sourceforge.net/docs/aafapiman/
      http://aaf.sourceforge.net/docs/pluginapiman/index.html

New APIs:
  IAAFPCMDescriptor, IAAFImportDescriptor, IAAFPhysicalDescriptor,
  IAAFRecordingDescriptor, IAAFSoundDescriptor, IAAFAuxiliaryDescriptor,
  IAAFDescriptiveFramework, IAAFDescriptiveMarker, IAAFKLVDataDefinition,
  IAAFTaggedValueDefinition, IEnumAAFKLVDataDefs, IEnumAAFTaggedValueDefs
  AAFGetLibraryVersion, AAFGetLibraryPathNameBufLen, AAFGetLibraryPathName

  see http://aaf.sourceforge.net/docs/aafapiman/

APIs with modified behaviour:
  IAAFMob::Copy() and IAAFMob::CloneExternal() now work
  IAAFFile::SaveCopyAs() now works
  IAAFFile::GetRevision() returns file version instead of a hard-coded value
  IAAFDataDef interfaces revised to support data definitions that are
    deemed to be equivalent:
      IsPictureKind(), IsSoundKind(), IsTimecodeKind(),
      DoesDataDefConvertTo(), DoesDataDefConvertFrom()
  AAFFileOpenExistingRead(), AAFFileOpenExistingModify() now merge file model
    with SDK builtin model
  AAFLoadLibrary() plugin search now looks under "aafext/" on all platforms

New header files:
  AAFCompressionDefs.h - UIDs for known compressed essence formats
  CAAFBuiltinDefs.h    - convenience classes

Plugin Codec changes:
  Added DV functionality to CDCI plugin codec
  Added PCM audio plugin codec (supporting BWF and SMPTE 382M audio essence)
  AIFC codec incorrect bytesPerFrame bug fixed
  Removed 2GB filesize limit in CDCI codec

New Examples:
  ExportDV, ImportDV
  ExportPCM, ImportPCM

New Utilities:
  aafextract - extract all essence streams from an AAF file as separate files
  aaf2xtl - AAF to Microsoft XTL utility
            see Utilities/aaf2xtl/doc/Aaf2XtlSoftwareDescription.pdf
  aafdump - structured storage dumper using choice of libgsf/ole32 API

Portability:
  - Linux x86-64 platform supported
  - Added UTF-8 filename support
  - added support for libgsf structured storage in addition to SchemaSoft
  - Win32/i686Linux/PPCDarwin SchemaSoft libraries can now write >2GB files

Removed features:
  - OMF libraries are no longer part of the AAF SDK project.  The libraries
    can be downloaded from http://www.aafassociation.org/download/
  - Support for Mac OS 9 has been removed


Compatibility with earlier releases
-----------------------------------

- Files generated by the AAF v1.1.x SDK cannot be read by earlier AAF SDKs,
  due to a limitation in the metadictionary processing code of SDKs prior
  to AAF v1.1.


Notes
-----

- The optional codec functionality using the ffmpeg library has been
  tested with the following version from the ffmpeg git repository:
    commit 969eb21ba21f0ed7154dd2a2fc754ef159df94a2
    date: Mon Mar 14 22:14:23 2011 -0700

- To create 4kB sector AAF files use any of the following interfaces.
  When embedding large amounts of essence in an AAF file (e.g. 10 minutes of
  DV material) 4kB sectors are necessary to overcome the 2GB filesize limit.
    AAFFileOpenNewModify( filename, AAF_FILE_MODE_USE_LARGE_SS_SECTORS, ...)
    AAFFileOpenNewModifyEx( filename, kAAFFileKind_Aaf4KBinary, ...)
    AAFCreateRawStorageDisk(...) followed by
      AAFCreateAAFFileOnRawStorage(..., kAAFFileKind_Aaf4KBinary, ...)


AAF KLV implementation implementation issues
--------------------------------------------

The AAF KLV implementation was developed with the goal of being a
compliant implementation of SMPTE 377M Material eXchange Format (MXF),
based on the belief that this was technically possible.

In this release, there are a few known outstanding issues.

- The AAF MetaDictionary object is written to the file on output and,
if present, read from the file on input, in order to support reliable
parsing of any extension data in the file. This facility is not a standard
part of MXF.

- In order to read typical MXF files (which do not contain a
MetaDictionary), the implementation can fall back to its built-in
definitions when reading an MXF file without a MetaDictionary.
This fails when data is encountered that is not defined by the built-in
definitions. If a property without a definition is encountered, the SDK
cannot restore the property and the file open call will fail (although
note below an exception to this in the case of Header::PrimaryMob). If
an object without a definition is encountered, the SDK skips the object
as dark. Any strong reference to the dark object will fail to resolve
and if such a strong reference property exists in a file the file
will fail to open. It fails at OMKLVStoredObject::restoreObject(const
OMStrongObjectReference&), after _storage->object(id) returns NULL. An
example of this case is DescriptiveMarker::Description, which will
typically point to a subclass of DescriptiveFramework that is not
defined in the built-in definitions.  Weak references to dark objects
will trigger a similar error.  In all these cases a client will get
AAFRESULT_UNEXPECTED_EXCEPTION returned from the toolkit file open calls.

- An AAF Root object is written to the file on output, to strong
reference the Header and MetaDictionary objects. This is not a standard
part of MXF. The implementation does not require the AAF Root object to
be present in order to find the Header object of a typical MXF file.

- Support has been added to the SDK to process WeakReference<Mob> types,
such as is used by the Header::PrimaryMob property. However, this property
has not been added to the built-in definitions because its presence would
have broken backwards-compatibility with AAF v1.1.0 or v1.1.1. At a future
time, when v1.1.2 is widely deployed, there may be a case for adding
Header::PrimaryMob to the built-in definitions. In order to read typical
MXF OP Atom files (which contain a Header::PrimaryMob property),
the implementation filters out this property so that its presence does
not trigger a run-time error caused by the lack of a definition.

- The version number (byte 8) in the KLV key of KLV Fill items is
frequently incorrect in MXF implementations. It is often v1, instead of
v2. The AAF KLV implementation outputs v1, and will accept v1 or v2 on input.

- Modification of an existing MXF file has only been tested in a
limited case. The successful test was to run the OpenExistingModify
test with default parameters. The test creates a metadata-only file,
which is then modified. The test changes values of existing properties,
adds new objects, including an object with a stream property, and saves
the file. This is not a typical workflow as
metadata-only MXF files are uncommon.

- The SDK fails to open AAF KLV files that contain extension weak reference
properties. The toolkit relies on the target path to find objects
referenced by weak reference properties.  The target paths for built-in
weak references are known but the paths for extensions are not and need
to come from the file. AAF KLV files (unlike AAF Structured Storage files)
do not store the target paths.

- MXF essence generated by an AAF codec uses a fixed default essence
element key (within the MXF essence stream) instead of the correct essence
element key as defined by the particular MXF essence mapping. The default
value used is that of the essence element node defined by the MXF Generic
Container (SMPTE 379M). The correct essence element key can be specified by
client code creating the MXF essence stream directly.

- IAAFMasterMob::AddMasterSlot creates a SourceClip contained directly by
a MobSlot, and not within a Sequence. This is not strictly valid for MXF.

- A workaround is used to deal with opening files in which a built-in
property definition is not in the file's metadictionary. The workaround is
to make the property optional by default to prevent an attempt to retrieve
the value of a property that doesn't exist in the file.


Structured Storage implementation (where applicable)
----------------------------------------------------

The AAF SDK typically requires an implementation of Structured Storage
to be provided on the platform. This may be provided as part of the
operating system, as part of an another application, as a proprietary
library or as an open source library.

For the cases where such a library is not already
available, a pre-compiled Structured Storage library is provided
(libSSRW2C.a and ssrw_c.lib) for use on the supported platforms. The
pre-compiled Structured Storage library is licensed under an agreement
between the AAF Association and a proprietary Structured Storage library
vendor:
  http://www.aafassociation.org/html/licenses/SchemaSoftTerms.pdf
  (reproduced in text form at the end of this document)

This proprietary library may be redistributed as part of the AAF SDK under
the conditions of that agreement. If you need to port this proprietary
Stuctured Storage library to another platform, please get in touch with the
AAF Association (info@aafassociation.org).  Below is the list of all
pre-compiled Structured Storage proprietary libraries in the AAF SDK.

    AAFWinSDK/sss-impl/ssrw_c.lib
    AAFi686LinuxSDK/g++/sss-impl/libSSRW2C.a
    AAFSparcSolarisSDK/g++/sss-impl/libSSRW2C.a
    AAFPPCDarwinSDK/g++/sss-impl/libSSRW2C.a
    AAFPPCDarwinSDK/g++/sss-impl/libSSRW2C.dylib
    AAFi386DarwinSDK/g++/sss-impl/libSSRW2C.a
    AAFi386DarwinSDK/g++/sss-impl/libSSRW2C.dylib
    AAFUniversalDarwinSDK/g++/sss-impl/libSSRW2C.a
    AAFUniversalDarwinSDK/g++/sss-impl/libSSRW2C.dylib
    AAFMipsIrixSDK/MIPSpro/sss-impl/libSSRW2C.a
    AAFx86_64LinuxSDK/g++/sss-impl/libSSRW2C.a

As an alternative, the open source libgsf library is also
supported with some limitations - see Known Issues below for details.


Known Issues
------------
- The pre-compiled Structured Storage implementation provided for Irix and
  the MIPSPro 7.3.1 compiler has the following limitations:
    ScaleTest failure for embedded essence streams >2GB in Structured Storage
	files with 4096 byte sectors
  UTF8FileNameTest failure for opening filenames containing international
  characters

- The SDK will fail at runtime when compiled using the MIPSpro 7.4.1
  C++ compiler.  For example, InfoDumper and ComModAAF will abort with:
  Assertion failed:
    _elementType && TypeDefinition::null() != _elementType,
    file AAFObjectModel.cpp, line 2826

- The Microsoft Structured Storage implementation (ole32.dll) (part of the
  MS Windows platform) can fail when reading or writing 512-byte Structured
  Storage AAF files containing a large number of objects. This does not
  occur with the pre-compiled Structured Storage implementation provided
  with the AAF SDK or the libgsf implementation. The performance and
  scalability of the AAF SDK and a Structured Storage library can be
  evaluated using the ScaleTest scripts.

- The libgsf Structured Storage implementation has the following limitations
  in conjuction with the AAF SDK:
  - No edit-in-place functionality.  This will cause a run-time failure in
    the AAFFileOpenExistingModify() interface call.
  - No RawStorage functionality causing the following interfaces to fail
    - AAFFileOpenNewModifyEx()
    - AAFCreateRawStorageDisk()
    - AAFCreateRawStorageCachedDisk()
    - AAFCreateAAFFileOnRawStorage()
      
  In practice these limitations restrict a client application's use of the SDK
  to only "Import AAF" and "Export AAF" operations using the following APIs:
    - AAFFileOpenExistingRead() (importing from an existing AAF file)
    - AAFFileOpenNewModify() (exporting to a new AAF file)

  To select the libgsf implementation and assuming you have libgsf installed
  under /usr/local, run make as follows
    make LIBGSF_PATH=/usr/local

- The IAAFTypeDefRecord interface implementation does not result in 
  correct property values when calls to SetValue() or
  CreateValueFromValues() are mixed with calls to RegisterMembers().
  This can happen regardless of the order of these calls.  
  In addition, the GetValue() method should not be used following a call
  to RegisterMembers() as it will result in incorrect results.
  If you use RegisterMembers(), confine Record property creation to the use of
  SetStruct() and CreateValueFromStruct() and Record property reading to the
  use of GetStruct().

- There are four divergences between the current SMPTE metadata
  spreadsheet (AAFMetaDict.xls) and AAFMetaDictionary.h. These divergences
  are applied in mkdict.awk as AAFMetaDictionary.h is generated from
  AAFMetaDict.csv. See "mkdict.awk override" comments in AAFMetaDictionary.h.


SchemaSoft license agreement
============================

Please be advised that the terms of the agreement between the AAF
Association and SchemaSoft Corporation allows us (the AAF Association) to
make available the Object Code contained in ssrw_c.lib and/or libSSRWC.a
under the following terms:

Use of Object Code
------------------
SchemaSoft grants a non-exclusive license in and to the Software in Object
Code form:

(a) to use and execute the Software for purposes of serving the Licensee's
    internal needs;
(b) to make, use, reproduce, have reproduced, display, incorporate, bundle,
    import, offer for sale, sell, sublicense and/or otherwise distribute by
    any means now known or hereafter developed (including without limitation
    electronic software downloads), directly or indirectly through multiple
    tiers or channels on a worldwide basis the Object Code and Derivative
    Works thereof authorized to be made hereunder, in whole or in part, only
    as part of a Licensee Product, statically or dynamically linked thereto;
    and
(c) to make, use, reproduce and distribute the Object Code or Derivative
    Works thereof for purposes of maintaining and supporting any Licensee
    Product,

provided always that any use, reproduction or distribution of the Object
Code will only be in conjunction with and as a part, statically or
dynamically linked, to the Licensee Product.