Media Authoring
with Java API

tv.amwa.maj.record
Interface SourceReferenceValue

All Known Implementing Classes:
SourceReferenceValue

public interface SourceReferenceValue

Specifies a reference to a clip of source material, specified by material identifier, slot number and start time offset components. Source reference values are used to specify source clip segments.

The interpretation of a source reference value depends on the context where it is used. The value of a source reference can be explicit or relative to its context. Source references are often used to build a chain of references that can be used to trace the original source of some material.

Three different kinds of reference can be identified from the value of the source id property of a source reference. These are defined as:

  1. Source id property is present and has a non-nil value. An explicit reference to a mob by its unique mob id and mob slot id. An optional offset starting frame may also be provided.
  2. Source id property is present and is the zero mob id. This specifies that the source mob containing the source reference represents the original source material. Such references are the final link in source reference chains.
  3. The source id property is not present. This specifies that the reference is to another slot within the same mob, the mob owning source reference itself.

Original C name: aafSourceRef_t

Author:
Richard Cartwright
See Also:
SourceReferenceSegment, MobID, SourceReferenceValue, SourceClip

Method Summary
 MobID getSourceID()
          Returns the identifier of the mob being referenced.
 int getSourceSlotID()
          Returns the slot id of a mob slot within the referenced mob.
 long getStartTime()
          Returns the offset from the origin of the referenced mob's mob slot in edit units determined by the source clip's context.
 boolean isContextual()
          Returns true if this source reference is to another slot within the context of the same mob or false if it is a reference to a slot in another mob.
 boolean isOriginalSource()
          Return true if this source reference is to the original source material and false if it requires further resolution.
 void setSourceID(MobID sourceID)
          Sets the identity of mob being referenced.
 void setSourceSlotID(int sourceSlotID)
          Sets the slot id of the referenced mob slot within the referenced mob.
 void setStartTime(Long startTime)
          Returns the offset from the origin of the referenced mob's mob slot in edit units determined by the source clip's context.
 

Method Detail

getSourceID

@MobIDType
MobID getSourceID()
                  throws PropertyNotPresentException

Returns the identifier of the mob being referenced. If the property is the zero mob id, it means that the mob owning this source reference describes the original source.

Returns:
Source id component of the source reference.
Throws:
PropertyNotPresentException - The optional source id property is not present in this source reference, implying that the reference is to a slot in the same mob as the reference itself.

setSourceID

void setSourceID(@MobIDType
                 MobID sourceID)

Sets the identity of mob being referenced. If the property is the zero mob id, it means that the mob owning this source reference describes the original source. Set the source id to null to indicate that the reference is to a slot in the mob owning this reference.

Parameters:
sourceID - Source id component of the source reference.

getSourceSlotID

@SlotID
int getSourceSlotID()

Returns the slot id of a mob slot within the referenced mob. If the source id of this value is the zero mob id then the source mob slot value shall also be set to 0.

Returns:
Slot component of the source reference, specified by slot id.

setSourceSlotID

void setSourceSlotID(@SlotID
                     int sourceSlotID)
                     throws IllegalArgumentException

Sets the slot id of the referenced mob slot within the referenced mob. If the source id of this value is the zero mob id then the source slot value shall also be set to 0.

Parameters:
sourceSlotID - Slot component of source reference, specified by slot id.
Throws:
IllegalArgumentException - Trying to set a non-zero value when the source id is the zero mob id or the slot id is negative.

getStartTime

@PositionType
long getStartTime()
                  throws PropertyNotPresentException

Returns the offset from the origin of the referenced mob's mob slot in edit units determined by the source clip's context. If the source id of this value is the nil mob id, then the start time shall also be set to 0.

Returns:
Offset from the origin of the referenced content.
Throws:
PropertyNotPresentException - The optional start time property is not present, indicating that the reference is in the context of a static mob slot rather than a timeline or event mob slot.

setStartTime

void setStartTime(@PositionType
                  Long startTime)
                  throws IllegalArgumentException

Returns the offset from the origin of the referenced mob's mob slot in edit units determined by the source clip's context. If the source id of this value is the null mob id then the start time shall be set to 0.

Set this optional property to null to omit it, indicating that this reference is in the context of a static mob slot rather than a timeline or event mob slot.

Parameters:
startTime - Offset from the origin of the referenced content.
Throws:
IllegalArgumentException - Trying to set a non-zero value when the source id is the zero mob id.

isOriginalSource

boolean isOriginalSource()

Return true if this source reference is to the original source material and false if it requires further resolution.

Returns:
Is this reference to the original source material?
See Also:
isOriginalSource(), SourceReferenceValue.originalSource()

isContextual

boolean isContextual()

Returns true if this source reference is to another slot within the context of the same mob or false if it is a reference to a slot in another mob.

Returns:
Is this reference to another slot in the context of the same mob?
See Also:
isContextual(), SourceReferenceValue.inContextReference(int), SourceReferenceValue.inContextReference(int, Long)

Media Authoring
with Java API

(c) 2007-2008 Richard Cartwright, all rights reserved. Subject to the terms of the AAF SDK Public Source License.