AAF Release Notes

AAF SDK v1.2.0

2020-09-24
This SDK is the reference implementation of the Advanced
Authoring Format (AAF) version 1.2. 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:
Windows 10, Visual Studio 2013
MacOS 10.15.6 Catalina, x86-64, Xcode 7
MacOS 11.6 Big Sur, ARM64, Xcode 12
x86_64-Linux, Ubuntu Xenial, gcc 4.8

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.6 to v1.2.0
Replace the build system with CMake-based system.

Versioning:
Deprecate AAFSDKBuild.h
The version is specified in top-level CMakeLists.txt and can be overwritten when generating a build system, e.g.:
 cmake -G "Visual Studio 12 2013 Win64" -DPLATFORM=vc11 -DARCH=x64 -DAAFSDK_VERSION_MAJOR=3 -DAAFSDK_VERSION_MINOR=2 -DAAFSDK_VERSION_PATCH=1 ..\..

- Interfaces and corresponding dictionary definitions to support metadata defined by MXF Generic Container mapping standards:
-- SMPTE ST 377-4 (MXF Multichannel Audio Labeling Framework metadata)
--- IAAFTypeDefGenericCharacter
---- Provide support for character types other than UTF-16.
--- IAAFAudioChannelLabelSubDescriptor
--- IAAFGroupOfSoundfieldGroupsLabelSubDescriptor
--- IAAFMCALabelSubDescriptor
--- IAAFSoundfieldGroupLabelSubDescriptor
-- SMPTE ST 422:2013:
--- IAAFJPEG2000SubDescriptor
-- SMPTE ST 381-2:2011:
--- IAAFMPEG4VisualSubDescriptor
--- IAAFMPEGAudioDescriptor
-- SMPTE ST 381-3:2013 AVCSubDescriptor:
--- IAAFAVCSubDescriptor

- Interfaces to improve file I/O performance:
-- IAAFAsyncStreamRawStorage
--- Extends IAAFRandomRawStorage with methods that support asynchronous file I/O.
-- IAAFIOCompletion
--- Provides support for asynchronous file I/O with IAAFAsyncStreamRawStorage.
-- IAAFSaveIntermediate
--- Extends IAAFFile with SaveIntermediate() call performs faster save operation creating AAF SDK-readable but not necessarily valid file.
-- IAAFCopyByte
--- Extends IAAFRandomRawStorage with WriteCopyByteAt() for efficient filling of contiguous space on storage.
-- IAAFStreamRawStorage
--- Extends IAAFRandomRawStorage with methods for efficient reading and writing large chunks of data and improves performance of stream access interfaces.
-- IAAFPlainStreamData2
--- Extends IAAFPlainStreamData with calls that support asynchronous and read scatter/write gather file I/O operations.
-- IAAFTypeDefStream2
--- Extends IAAFTypeDefStream with calls that support asynchronous and read scatter/write gather file I/O operations.

- Interfaces to improve metadata access:
-- IAAFDataDef4:
--- Extends IAAFDataDef with IsDataKind() method.
-- IAAFEssenceDescriptor2
--- Extends IAAFEssenceDescriptor with methods to access SubDescriptors property of EssenceDescriptor.
-- IAAFHeader3
--- Extends IAAFHeader2 with CreateEmptyDescriptiveSchemes() and RemoveDescriptiveSchemes() methods.
-- IAAFSubDescriptor
--- Abstract base class for SubDescriptors.
-- IEnumAAFSubDescriptors
--- Support for accessing SubDescriptors property of EssenceDescriptor.

- Interfaces to improve metadata processing:
-- IAAFSearchSource2
--- Extends IAAFSearchSource with SearchSourceAdvanced() method that provides better results when searching across mixed audio and video rates.
-- IAAFSearchSource3
--- Extends IAAFSearchSource with methods that support source search across multichannel audio tracks.
-- IAAFFindSourceInfo2
--- Extends IAAFFindSourceInfo with GetMultichannelSourceReference() method to support source search across multichannel audio tracks.
-- IAAFMob3
--- Extends IAAFMob with CloneExternalAdvanced() method that allows source file to be closed before destination file is saved. The method doesn't support deferred copying of essence and index data.

- Interfaces to improve plugin support:
-- IAAFEssenceDataStreamEx
--- Adds sample index access methods.
-- IAAFDictionaryExtension
--- For use by plugins to register metadata in the dictionary.

- ST 377 compilance improvements:
-- Add strict/permissive MXF parser modes; the permissive mode is on by default. When restoring MXF in permissive mode discard properties that are present on object in the file but aren’t specified as being part of the object's class definition in the dictionary. This allows to accept invalid MXF files that put properties of one class in instances of another class.
-- Always use standard Timecode data definition for new Timecode components and containing Sequences.
-- Update IAAFFile::Open() to instantiate all axiomatic definitions in metadictionary of a new file. As a side-effect this adds previously missing properties to the Primer (Size, ClassDefinitions, etc.)
-- Update KLV parser to recognize static local keys assigned by SMPTE to Root Object Directory and Root Format Version properties.
-- Update KLV parser to recognize values of extendible enumeration properties stored as SMPTE ULs in ST377-compliant files.
-- Add Root properties Meta Dictionary, Header and Format Version to the Primer in KLV-encoded files.
-- Support for enforce ST 377 constraints in KLV-encoded files, currently compiled out as it produces files unreadable by older SDKs:
--- Update KLV writer to enable it to use the standard local keys to identify Object Directory and Format Version in the file. The writer changes are currently turned off to avoid breaking forward compatibility.
--- If target file is ST377-compliant use Root SMPTE UL, use SMPTE Root Format Version local tag, and don't write Object Directory. Object Directory writing methods still use legacy Object Directory GUID and invalid Root Object Directory static local tag; these have to be fixed if Object Directory needs to appear in 377-compliant files.
--- Store ProductVersion properties as 10 byte values when writing ST377-compliant file. Writing containers of 10 byte ProductVersion elements to ST377-compliant file is not implemented; throw an exception when attempting to save such properties to ST377-compliant file.
--- Store values of extendible enumeration properties as SMPTE ULs when writing ST377-compliant file.

- Implement SetPrimaryMob() and GetPrimaryMob() calls on IAAFHeader2 interface:
-- Implement support for Weak Reference to Mob.
-- Add a hack to skip saving Header::PrimaryMob property definition if the property value is not set:
--- Older versions of AAF SDK cannot open file containing definitions or instances of weak references to mobs, such as PrimaryMob. This change reduces compatibility impact by removing from a file traces of weak references to mobs if they are not needed. This is hard-coded to deal only with PrimaryMob.
-- If it's missing in file's class definition register Header::PrimaryMob property before instantiating the Header. This allows to open older files that are missing Header::PrimaryMob definition.

- Add support for unknown (-1) length:
-- Update Component classes and API to support -1 as the value of unknown length.
-- Update IAAFSourceMob interface implementation to support unknown (-1) length:
--- Remove the undocumented behavior of IAAFSourceMob's AppendTimecodeSlot() and SpecifyValidCodeRange() where they interpret input length of -1 as 24 hours.
--- Fix IAAFSourceMob::AddPulldownRef() to specify a valid name for new Mob Slots.
--- Fix IAAFSourceMob::AddPulldownRef() to correctly locate first non-zero length component of a sequence.
--- Fix memory leaks in IAAFSourceMob::AddPulldownRef().
-- Update relevant functionality, such as IAAFMob::SearchSource() to support processing of Components with unknown length.

- Enforce Mob Slot specific constraints in the API:
-- Update IAAFSequence implementation to restrict component types to those allowed by containing Mob Slot, according to AAF Object Specification.
-- When enforcing Mob Slot constraints distinguish between unattached Components and those attached to a Mob Slot.

- Update Object Manager (OM) implementation to replace Structured Storage stored names with 16 byte UIDs as unique identifiers of referenced objects. The change reduces AAF Toolkit memory usage by 10%.

- Support deferred stream writing, accessible via IAAFTypeDefStream::SetCallback(), for KLV-encoded files.

- Various:
-- IAAFMasterMob::AddMasterSlot(): Create Sequence as a Segment of new TimelineMobSlot.
-- Update IAAFMob::SearchSource() and related calls to support searching for the kAAFPhysicalMob kind.
-- Close() opened ImplAAFFile instance before destroying it. This removes requirement to call IAAFFile::Close() before Release().
-- Add AAF_OMIT_WINDOWS_DATA_TYPES_DEFINITIONS macro to allow to skip definition of Windows Data Types on non-Windows platforms. It helps to avoid conflicts in projects that have their own definition of Windows types.

- Metadata definitions:
-- Deprecate AAFMetaDict.xls, instead use AAFMetaDictionary.h as the metadata dictionary source.
-- Add Data Essence data definition.
-- Add several SMPTE timecode data definitions.
-- Update metadata dictionary definitions and the API to add new values specified by SMPTE ST 377-1:2011 to enumeration types:
--- ColorSitingType
--- RGBAComponentKind
--- SignalStandardType
-- Update metadata dictionary definitions to add new values specified by SMPTE ST 377-1:2011 to extendible enumeration types:
--- TransferCharacteristicType
--- ColorPrimariesType
--- CodingEquationsType

- MXFDump updates:
-- Use Primer Pack to recognize dynamically allocated local keys.
-- Update to the latest version of MXF metadictionary.
-- Add '--show-anc' option for printing contents of ANC Frame Elements.
-- Recognize VC-1 and VC-3 essence element labels.

- InfoDumper updates:
-- Support the case when the name of an extendible enumeration is not available (the name is missing from dictionary or dictionary is not present.)
-- Dump DataDefinition and CodecDefinition IDs instead of names when -identifybyID is specified.
-- Ignore property values errors to continue dumping object's contents even if one of its properties cannot be processed.
-- Don't stop following failure to process DM Segments.
-- Display string properties whose type is defined by AvidTypeDefGenericCharacter (e.g. RFC5646SpokenLanguage).
-- Along with Enumeration value names print their AUID or integer values.

Fixes:
- Change OMKLVStoredObject::restoreObject(), and its callers OMStrongObjectReference::getValue() and OMStrongObjectReference::load(), to not expect a referenced object to get successfully restored. This allows to open KLV files with strong references to dark objects.
- Override ImplAAFOperationGroup's and ImplAAFSequence GetMinimumBounds() to find leaf object that points to the next mob and stop calling TraverseToClip() on sequences. Fixes SearchSource() on Master Mob slots with audio gain Operation Groups and multi-component Sequences.
- Ensure that copied ImplAAFObjects are marked as initialized. This allows to access copied (e.g. with IAAFMob::Copy()) objects using methods that require them to be initialized.
- In ImplAAFTypeDefRecord::internalSize() handle metadata restore case where record type definition has been fully initialized yet. Fixes calls such as ImplAAFTypeDefVariableArray::pvtCreateOMProperty() which uses the array element's internalSize() to determine the concrete class of an array OM property.
- Fix stack overflow during call to IAAFMob::SearchSource() when traversing of zero-length non-empty sequences.
- Do not validate the size of the passed in value in ImplAAFTaggedValue::SetValue because the type of the value and therefore its external size are unknown. Instead, rely on the call to ImplAAFTypeDefIndirect::SetActualPropertyValue() to check the value size.
- Do not restore optional stream properties with zero SIDs. This is intended to handle the case of zero IndexSID property in MXF files.
- Add a few missing class definitions to CAAFBuiltinDefs class.
- Do not allow modifications to the built-in dictionary, including setting local property IDs (PIDs), to avoid duplicate dynamically allocated PIDs in built-in property definitions and extension property definitions.
- Override FindSubSegment() in ImplAAFOperationGroup to allow SearchSource() traverse beyond Operation Groups. It is especially important for the case when Operation Group's input segment is a Sequence because the source segment will have offset and length from the Operation Group.
- During IAAFMob::CloneExternal(), copy Parameter Definitions to the destination Dictionary as part of the Dictionary merge.
- Fix infinite loop on 64-bit Mac OS X in ImplAAFPulldown::GetRemFramesDrop().
- Reject an KLV-encoded files with properties that do not belong to containing object.
- When copying objects across files (e.g. IAAFFile::SaveAs(), IAAFMob::CloneExternal()) copy all type definitions from the source to the destination file's dictionary.
- When merging dictionaries do not copy DMS-1 type definitions. The SDK reads but does not write DMS-1 metadata.
- Fix leaking ImplAAFEssenceData objects when invoking IAAFMob::CloneExternal() with kAAFIncludeMedia.
- Update IAAFTypeDefExtEnum::AppendElement() to handle duplicates: the method succeeds if name/value pair already exists, it fails if either name or value, but not both, already exist.
- When copying objects across files (e.g. IAAFFile::SaveAs(), IAAFMob::CloneExternal()) copy contents of Extendible Enumeration type definitions.
- For tests that support it turn on full validation of metadata during test file creation. There's nothing in the version history or in the code that explains why full validation was disabled. Having it on helps to detect a bug in ImplAAFTypeDefExtEnum::CreateValueFromName().
- Fix IAAFTypeDefExtEnum::CreateValueFromName() so that created PropertyValue has type TypeDefExtEnum and not TypeDefRecord.
- Ensure complete initialization of the dictionary object when opening files that are missing AAF dictionary.
- When copying objects across files (e.g. IAAFFile::SaveAs(), IAAFMob::CloneExternal()) recognize old style element names of built-in extendible enums.
- Add missing include guards in AAF SDK header files.
- Return an error from IAAFProperty::GetValue() when called on an uninitialized instance of AAFProperty. Fixes a crash trying to access unresolved (dark) Strong Reference property.
- Do not crash when trying to open a bad file with a Strong Reference Array referencing non-existent objects. Update IAAFSequence::GetComponentAt() to handle referenced but missing sequence components by returning AAFRESULT_OBJECT_NOT_IN_FILE.
- Do not reject KLV-encoded files with zero size string properties. Such properties are allowed in MXF.
- Fix segmentation fault during IAAFFile::Save() after a call to IAAFMob::CloneExternal()):
-- Do not detach its properties and referenced objects when detaching an OMStorable. If an object or a property referenced by another object the object or the property are attached regardless of whether the referring object is attached or not.
- Fix copying of mob dependencies in IAAFMob::CloneExternal() to include mobs referenced by properties EssenceGroup::Choices, EssenceGroup::StillFrame, OperationGroup::Rendering, and CommentMarker::Annotation.
- In KLV-encoded file store AES3PCMDescriptor's FixedChannelStatusData FixedUserData properties as a 24-byte element array. This does not affect the dictionary, the parser and the access API that still treat these properties as a UInt8 array.
- Improve error handling in ImplAAFMetaDictionary and ImplAAFTypeDef classes:
-- ImplAAFMetaDictionary and related:
--- Add a set of check() utility routines to handle unexpected internal errors in Impl classes.
--- Improve handling of errors that can result in use of NULL pointers in ImplAAFMetaDictionary class:
---- Methods that use _dataDictionary will throw an error if _dataDictionary is invalid.
---- create() will throw and error if it fails to create a valid object.
---- Methods will throw an error if they cannot handle a NULL pointer.
---- Methods will throw an error if they cannot handle a failed function call.
--- In ImplAAFBuiltinClasses::NewBuiltinClassDef( ) handle failues in ImplAAFMetaDictionary::pvtCreateMetaDefinition().
--- Explicitly declare overrides of virtual method as virtual - for readability.
-- ImplAAFTypeDef and its children:
--- Implement unimplemented ImplAAFTypeDef's "pure virtual" methods in derived classes.
--- Make ImplAAFTypeDef’s "pure virtual" methods fail explicitly to prevent them from being called.
--- Make ImplAAFTypeDef::NativeSize() and ProValSize(), and OMType::internalSize() and externalSize() fail explicitly when called for type definitions of variable size.
--- Make unimplemented OMType overrides in ImplAAFTypeDefSet and ImplAAFTypeDefStream fail explicitly.
- Update IAAFSearchSource::SearchSource() to return AAFRESULT_TRAVERSAL_NOT_POSS if it encounters a Pulldown object with Timecode as its input segment.
- Fix valid weak reference assertion violation during save of a modified existing file:
-- Copy target tag when copying OMWeakReferenceProperty. (This change was omitted from the set of changes to stop using deprecated OMWeakReference::reference().)
-- Strengthen void reference check in save() - reference has to be resolved or be resolvable.
-- Do not clear OMWeakReference’s target tag during save, unset target tag may prevent the property from being saved again.
- Correct Drop Frame TC calculation in IAAFTimecodeStream::SetPositionTimecode().
- Turn some debug-only asserts into run-time exceptions to avoid access violations.
- Fix failure in the Schemasoft library to open Structure Storage-encoded AAF files with truncated last sector.
- When calculating Sequence length ignore position of Events if the Sequence contains non-Events.
- Update the Schemasoft library-related hack in OMDataStreamProperty::save() to delay closing a stream until after the deferred data is written to the stream.
- Fix memory leaks.

Compatibility issues:
Files created with this version of AAF SDK and containing instances of classes derived from MCALabelSubDescriptor class trigger access violation when opened with previous versions of AAF SDK due to a bug in file restore functionality.
Files created with this version of AAF SDK and containing Header::PrimaryMob property value trigger access violation when opened with previous versions of AAF Toolkit due to a bug in file restore functionality.
IAAFSequence interface now enforces component semantics (type and length) when adding components to a Mob Slot.

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 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.
