Microsoft DirectX 8.0

IAMTimelineObj Interface

Provides methods for manipulating timeline objects in Microsoft® DirectShow® Editing Services (DES). All timeline objects implement this method, including source, effect, transition, track, group, and composition objects. Create a timeline object by calling the IAMTimeline::CreateEmptyNode method.

Requirements

Requires Qedit.h.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IAMTimelineObj MethodsDescription
GetStartStopRetrieves the object's start and stop times, relative to the object's parent.
GetStartStop2Equivalent to GetStartStop, but takes REFTIME values.
FixTimesRounds the specified start and stop times to the nearest frame boundaries, as defined by the parent group's frame rate setting.
FixTimes2Equivalent to FixTimes, but takes REFTIME values.
SetStartStopSets the object's start and stop times, relative to the timeline.
SetStartStop2Equivalent to SetStartStop, but takes REFTIME values.
GetPropertySetterRetrieves the object's property setter.
SetPropertySetterSets the object's property setter.
GetSubObjectRetrieves the subobject associated with this object.
SetSubObjectNot supported.
SetSubObjectGUIDSpecifies the globally unique identifier (GUID) of the subobject associated with this object.
SetSubObjectGUIDBEquivalent to SetSubObjectGUID, but takes a BSTR value.
GetSubObjectGUIDRetrieves the GUID of the subobject associated with this timeline object.
GetSubObjectGUIDBEquivalent to GetSubObjectGUID, but receives a BSTR value.
GetSubObjectLoadedDetermines whether the object's subobject pointer has been set.
GetTimelineTypeRetrieves the object's type.
SetTimelineTypeNot supported.
SetUserIDSets an application-defined identifier for the object.
GetUserIDRetrieves the object's application-defined identifier.
GetGenIDRetrieves the object's generated identifier.
SetUserNameSets an application-defined name for the object.
GetUserNameRetrieves the object's application-defined name.
SetUserDataSets application-defined persistent data.
GetUserDataRetrieves the application-defined persistent data.
SetMutedSets the object's muted state.
GetMutedRetrieves the object's muted state.
SetLockedSets the object's editing state to locked or unlocked.
GetLockedRetrieves the object's editing state (locked or unlocked).
GetDirtyRangeNot supported.
GetDirtyRange2Not supported.
SetDirtyRangeNot implemented.
SetDirtyRange2Not implemented.
ClearDirtyNot supported.
RemoveRemoves this object from the timeline, for reinsertion elsewhere.
RemoveAllPermanently removes this object from the timeline, including subobjects and children.
GetTimelineNoRefNot supported.
GetGroupIBelongToNot supported.
GetEmbedDepthNot supported.

IAMTimelineObj::ClearDirty

IAMTimelineObj Interface

Not supported.

Syntax

HRESULT ClearDirty( void );

IAMTimelineObj::FixTimes

IAMTimelineObj Interface

Rounds the specified start and stop times to the nearest frame boundaries, as defined by the parent group's frame rate setting.

Syntax

HRESULT FixTimes(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

Parameters

pStart
Pointer to a variable that contains the start time, in 100-nanosecond units. If the call succeeds, this variable is set to the rounded time.
pStop
Pointer to a variable that contains the stop time, in 100-nanosecond units. If the call succeeds, this variable is set to the rounded time.

Return Value

Returns S_OK if successful, or E_NOTINTREE if the object is not part of a group.

Remarks

During rendering, DES rounds the object's start and stop times to the nearest frame boundary. However, DES does not overwrite the object's times. If you change the group frame rate, the rounded times are always calculated from the original times. For more information, see Frame Rates.

Use this method to determine accurate start and stop times in the rendered project. For example, you should seek to the rounded times, rather than the object's original start and stop times. Call GetStartStop to obtain the original times, and pass those values to FixTimes.

IAMTimelineObj::FixTimes2

IAMTimelineObj Interface

Rounds the specified start and stop times to the nearest frame boundaries, as defined by the parent group's frame rate setting. This method is equivalent to FixTimes, but takes REFTIME values.

Syntax

HRESULT FixTimes2(
    REFTIME *pStart,
    REFTIME *pStop
);

Parameters

pStart
Pointer to a variable that contains the start time, in seconds. If the call succeeds, this variable is set to the rounded time.
pStop
Pointer to a variable that contains the stop time, in seconds. If the call succeeds, this variable is set to the rounded time.

Return Value

Returns S_OK if successful, or E_NOTINTREE if the object is not part of a group.

IAMTimelineObj::GetDirtyRange

IAMTimelineObj Interface

Not supported.

Syntax

HRESULT GetDirtyRange(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

IAMTimelineObj::GetDirtyRange2

IAMTimelineObj Interface

Not supported.

Syntax

HRESULT GetDirtyRange2(
    REFTIME *pStart,
    REFTIME *pStop
);

IAMTimelineObj::GetEmbedDepth

IAMTimelineObj Interface

Not supported.

Syntax

HRESULT GetEmbedDepth(
    long *pVal
);

IAMTimelineObj::GetGenID

IAMTimelineObj Interface

Retrieves the object's generated identifier. The identifier is a reserved number; applications should not use it.

Syntax

HRESULT GetGenID(
    long *pVal
);

Parameters

pVal
Pointer to a variable that receives the generated identifier.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineObj::GetGroupIBelongTo

IAMTimelineObj Interface

Not supported.

Syntax

HRESULT GetGroupIBelongTo(
    IAMTimelineGroup **ppGroup
);

IAMTimelineObj::GetLocked

IAMTimelineObj Interface

Retrieves the object's editing state (locked or unlocked). A locked state indicates that the object should not be edited; an unlocked state indicates that the object can be edited. The timeline does not enforce the lock. The locked setting exists only for the convenience of the application.

Syntax

GetLocked(
    BOOL *pVal
);

Parameters

pVal
Pointer to a Boolean variable that receives the object's editing state. If the value is TRUE, the object is locked and should not be edited. If FALSE, the object is unlocked and can be edited.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineObj::GetMuted

IAMTimelineObj Interface

Retrieves the object's muted state.

Syntax

HRESULT GetMuted(
    BOOL *pVal
);

Parameters

pVal
Pointer to a Boolean variable that receives a value indicating the muted state. If the value is TRUE, the object and its children are muted.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

Remarks

If an object's parent is muted, the object is muted regardless of its muted state. When the parent is no longer muted, the object's previous muted state is restored.

IAMTimelineObj::GetPropertySetter

IAMTimelineObj Interface

Retrieves the object's property setter. When the object is rendered, the property information contained in the property setter is applied to the object.

Syntax

HRESULT GetPropertySetter(
    IPropertySetter **pVal
);

Parameters

pVal
[out, retval] Address of a pointer that receives the property setter's IPropertySetter interface. If the object does not have a property setter, the value is set to NULL.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

Remarks

If the value returned in pVal is not NULL, the IPropertySetter interface has an outstanding reference count. Be sure to release the interface when you are finished using it.

IAMTimelineObj::GetStartStop

IAMTimelineObj Interface

Retrieves the object's start and stop times, relative to the object's parent.

Syntax

HRESULT GetStartStop(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

Parameters

pStart
Pointer to a variable that receives the start time, in 100-nanosecond units.
pStop
Pointer to a variable that receives the stop time, in 100-nanosecond units.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

Remarks

Compositions, groups, and tracks always have a start time of 0.

During rendering, DES rounds an object's start and stop times to the nearest frame boundary. However, DES does not overwrite the object's times. If you change the group frame rate, the rounded times are always calculated from the original times. For more information, see Frame Rates.

To determine the start and stop times in the rendered project, pass the values returned by GetStartStop to the FixTimes method.

IAMTimelineObj::GetStartStop2

IAMTimelineObj Interface

Retrieves the object's start and stop times, relative to the object's parent. This method is equivalent to GetStartStop, but takes REFTIME values.

Syntax

HRESULT GetStartStop2(
    REFTIME *pStart,
    REFTIME *pStop
);

Parameters

pStart
Pointer to a variable that receives the start time, in seconds.
pStop
Pointer to a variable that receives the stop time, in seconds.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineObj::GetSubObject

IAMTimelineObj Interface

Retrieves the subobject associated with this object.

Syntax

HRESULT GetSubObject(
    IUnknown **pVal
);

Parameters

pVal
[out, retval] Address of a pointer that receives the subobject's IUnknown interface. If the object does not have a subobject, the value is set to NULL.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

Remarks

Every timeline object can hold a pointer to an associated subobject. For example, the subobject of an effect is typically a Microsoft® DirectX® Transform object that generates the effect.

If the value returned in pVal is not NULL, the IUnknown interface has an outstanding reference count. Be sure to release the interface when you are finished using it.

IAMTimelineObj::GetSubObjectGUID

IAMTimelineObj Interface

Retrieves the GUID of the subobject associated with this timeline object.

Syntax

HRESULT GetSubObjectGUID(
    GUID *pVal
);

Parameters

pVal
Pointer to a variable that receives the GUID of the subobject, or GUID_NULL if the object does not have a subobject.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineObj::GetSubObjectGUIDB

IAMTimelineObj Interface

Retrieves the GUID of the subobject associated with this timeline object. This method is equivalent to GetSubObjectGUID, but receives a BSTR value.

Syntax

HRESULT GetSubObjectGUIDB(
    BSTR *pVal
);

Parameters

pVal
[out, retval] Pointer to a BSTR that receives a string representing the subobject GUID.

Return Value

Returns S_OK if successful. Otherwise, returns E_OUTOFMEMORY or another HRESULT value indicating the cause of the error.

Remarks

The method allocates memory for the string. The application must call SysFreeString to free the memory.

IAMTimelineObj::GetSubObjectLoaded

IAMTimelineObj Interface

Determines whether the object's subobject pointer has been set.

Syntax

HRESULT GetSubObjectLoaded(
    BOOL *pVal
);

Parameters

pVal
Pointer to a variable that receives a Boolean value. If the value is TRUE, the subobject pointer has been set. If FALSE, the pointer has not been set.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineObj::GetTimelineNoRef

IAMTimelineObj Interface

Not supported.

Syntax

HRESULT GetTimelineNoRef(
    IAMTimeline **ppResult
);

IAMTimelineObj::GetTimelineType

IAMTimelineObj Interface

Retrieves the object's type.

Syntax

HRESULT GetTimelineType(
    TIMELINE_MAJOR_TYPE *pVal
);

Parameters

pVal
Pointer to a variable that receives a member of the TIMELINE_MAJOR_TYPE enumerated type, indicating the type of object.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineObj::GetUserData

IAMTimelineObj Interface

Retrieves the application-defined persistent data.

Syntax

HRESULT GetUserData(
    BYTE *pData,
    long *pSize
);

Parameters

pData
Pointer to a buffer that receives the data. To determine the size of buffer to allocate, set this parameter to NULL. The required size is returned in pSize.
pSize
Pointer to a variable that receives the size of the data, in bytes.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineObj::GetUserID

IAMTimelineObj Interface

Retrieves the object's application-defined identifier.

Syntax

HRESULT GetUserID(
    long *pVal
);

Parameters

pVal
Pointer to a variable that receives the application-defined identifier.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineObj::GetUserName

IAMTimelineObj Interface

Retrieves the object's application-defined name.

Syntax

HRESULT GetUserName(
    BSTR *pVal
);

Parameters

pVal
[out, retval] Pointer to a BSTR that receives the name of the object.

Return Value

Returns S_OK if successful. Otherwise, returns E_OUTOFMEMORY or another HRESULT value indicating the cause of the error.

Remarks

The method allocates memory for the string. The application must call SysFreeString to free the memory.

IAMTimelineObj::Remove

IAMTimelineObj Interface

Removes this object from the timeline (including subobjects but not children), for reinsertion elsewhere.

Syntax

HRESULT Remove( void );

Return Value

Returns S_OK.

Remarks

Call this method only if the application will immediately insert the object back into the timeline. It is an invalid operation to call this method without then reinserting the object. To remove an object permanently, call RemoveAll.

IAMTimelineObj::RemoveAll

IAMTimelineObj Interface

Permanently removes this object from the timeline, including subobjects and children.

Syntax

HRESULT RemoveAll( void );

Return Value

Returns S_OK.

Remarks

To remove an object for the purpose of reinserting it elsewhere in the timeline, call Remove.

IAMTimelineObj::SetDirtyRange

IAMTimelineObj Interface

Not implemented.

Syntax

HRESULT SetDirtyRange(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

IAMTimelineObj::SetDirtyRange2

IAMTimelineObj Interface

Not implemented.

Syntax

HRESULT SetDirtyRange2(
    REFTIME Start,
    REFTIME Stop
);

IAMTimelineObj::SetLocked

IAMTimelineObj Interface

Sets the object's editing state to locked or unlocked. A locked state indicates that the object should not be edited; an unlocked state indicates that the object can be edited. The timeline does not enforce the lock. The locked setting exists only for the convenience of the application.

Syntax

HRESULT SetLocked(
    BOOL newVal
);

Parameters

newVal
Boolean value that specifies the object's editing state. If TRUE, the object is locked and should not be edited. If FALSE, the object is unlocked and can be edited.

Return Value

Returns S_OK.

IAMTimelineObj::SetMuted

IAMTimelineObj Interface

Sets the object's muted state. A muted object is not rendered, but it remains in the timeline.

Syntax

HRESULT SetMuted(
    BOOL newVal
);

Parameters

newVal
Flag that specifies the muted state. If TRUE, the object and all of its children are muted.

Return Value

Returns S_OK.

Remarks

Muting an object also mutes any children contained in the object. For example, if you mute a track, the transitions, sources, and effects in that track are also muted. Once the object is no longer muted, its children revert to their previous state, which might be muted or unmuted.

IAMTimelineObj::SetPropertySetter

IAMTimelineObj Interface

Sets the object's property setter. When the object is rendered, the property information contained in the property setter is applied to the object. Call this method on transition and effect objects.

Syntax

HRESULT SetPropertySetter(
    IPropertySetter *newVal
);

Parameters

newVal
Pointer to the property setter's IPropertySetter interface.

Return Value

Returns S_OK.

IAMTimelineObj::SetStartStop

IAMTimelineObj Interface

Sets the object's start and stop times, relative to the object's parent.

Syntax

HRESULT SetStartStop(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

Parameters

Start
New start time, in 100-nanosecond units, or –1 to keep the existing start time.
Stop
New stop time, in 100-nanosecond units, or –1 to keep the existing stop time.

Return Value

Returns one of the following HRESULT values:

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_NOTIMPLNot implemented.

Remarks

Tracks, compositions, and groups do not implement this method. For these objects, the start time is always zero, and the stop time is the maximum stop time of the objects they contain.

Do not set overlapping times on source objects within the same track. Doing so can cause undefined behaviors.

For source objects, the start and stop times are independent of the media start and media stop times. Changing one pair of values does not change the other. To set the media start and stop times, call the IAMTimelineSrc::SetMediaTimes method. For more information, see Time in DirectShow Editing Services.

IAMTimelineObj::SetStartStop2

IAMTimelineObj Interface

Sets the object's start and stop times, relative to the object's parent. This method is equivalent to SetStartStop, but takes REFTIME values.

Syntax

HRESULT SetStartStop2(
    REFTIME Start,
    REFTIME Stop
);

Parameters

Start
New start time, in seconds, or –1 to keep the existing start time.
Stop
New stop time, in seconds, or –1 to keep the existing stop time.

Return Value

Returns one of the following HRESULT values:

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_NOTIMPLNot implemented.

IAMTimelineObj::SetSubObject

IAMTimelineObj Interface

Not supported.

Syntax

HRESULT SetSubObject(
    IUnknown *newVal
);

IAMTimelineObj::SetSubObjectGUID

IAMTimelineObj Interface

Specifies the GUID of the subobject associated with this object.

Syntax

HRESULT SetSubObjectGUID(
    GUID newVal
);

Parameters

newVal
GUID of the subobject.

Return Value

Returns S_OK.

Remarks

The render engine creates an instance of the subobject as needed.

IAMTimelineObj::SetSubObjectGUIDB

IAMTimelineObj Interface

Specifies the GUID of the subobject associated with this object. This method is equivalent to SetSubObjectGUID but takes a BSTR value.

Syntax

HRESULT SetSubObjectGUIDB(
    BSTR newVal
);

Parameters

newVal
BSTR representing the GUID of the subobject.

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

IAMTimelineObj::SetTimelineType

IAMTimelineObj Interface

Not supported. Call the IAMTimeline::CreateEmptyNode method to create a new timeline object. Once an object is created, you cannot change its type.

Syntax

HRESULT SetTimelineType(
    TIMELINE_MAJOR_TYPE newVal
);

IAMTimelineObj::SetUserData

IAMTimelineObj Interface

Sets application-defined persistent data.

Syntax

HRESULT SetUserData(
    BYTE *pData,
    long Size
)

Parameters

pData
Pointer to a buffer containing the data.
Size
Size of the data, in bytes.

Return Value

Returns S_OK if successful, or E_OUTOFMEMORY if there is insufficient memory.

IAMTimelineObj::SetUserID

IAMTimelineObj Interface

Sets an application-defined identifier for the object.

Syntax

HRESULT SetUserID(
    long newVal
);

Parameters

newVal
Value that specifies the identifier. This identifier is used only by the application and can be any value.

Return Value

Returns S_OK.

IAMTimelineObj::SetUserName

IAMTimelineObj Interface

Sets an application-defined name for the object.

Syntax

HRESULT SetUserName(
    BSTR newVal
);

Parameters

newVal
Wide-character string that contains the name. Strings longer than 256 characters might be truncated.

Return Value

Returns S_OK.