Microsoft DirectX 8.0 |
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 methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IAMTimelineObj Methods Description GetStartStop Retrieves the object's start and stop times, relative to the object's parent. GetStartStop2 Equivalent to GetStartStop, but takes REFTIME values. FixTimes Rounds the specified start and stop times to the nearest frame boundaries, as defined by the parent group's frame rate setting. FixTimes2 Equivalent to FixTimes, but takes REFTIME values. SetStartStop Sets the object's start and stop times, relative to the timeline. SetStartStop2 Equivalent to SetStartStop, but takes REFTIME values. GetPropertySetter Retrieves the object's property setter. SetPropertySetter Sets the object's property setter. GetSubObject Retrieves the subobject associated with this object. SetSubObject Not supported. SetSubObjectGUID Specifies the globally unique identifier (GUID) of the subobject associated with this object. SetSubObjectGUIDB Equivalent to SetSubObjectGUID, but takes a BSTR value. GetSubObjectGUID Retrieves the GUID of the subobject associated with this timeline object. GetSubObjectGUIDB Equivalent to GetSubObjectGUID, but receives a BSTR value. GetSubObjectLoaded Determines whether the object's subobject pointer has been set. GetTimelineType Retrieves the object's type. SetTimelineType Not supported. SetUserID Sets an application-defined identifier for the object. GetUserID Retrieves the object's application-defined identifier. GetGenID Retrieves the object's generated identifier. SetUserName Sets an application-defined name for the object. GetUserName Retrieves the object's application-defined name. SetUserData Sets application-defined persistent data. GetUserData Retrieves the application-defined persistent data. SetMuted Sets the object's muted state. GetMuted Retrieves the object's muted state. SetLocked Sets the object's editing state to locked or unlocked. GetLocked Retrieves the object's editing state (locked or unlocked). GetDirtyRange Not supported. GetDirtyRange2 Not supported. SetDirtyRange Not implemented. SetDirtyRange2 Not implemented. ClearDirty Not supported. Remove Removes this object from the timeline, for reinsertion elsewhere. RemoveAll Permanently removes this object from the timeline, including subobjects and children. GetTimelineNoRef Not supported. GetGroupIBelongTo Not supported. GetEmbedDepth Not supported.
Not supported.
Syntax
HRESULT ClearDirty( void );
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.
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.
Not supported.
Syntax
HRESULT GetDirtyRange( REFERENCE_TIME *pStart, REFERENCE_TIME *pStop );
Not supported.
Syntax
HRESULT GetDirtyRange2( REFTIME *pStart, REFTIME *pStop );
Not supported.
Syntax
HRESULT GetEmbedDepth( long *pVal );
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.
Not supported.
Syntax
HRESULT GetGroupIBelongTo( IAMTimelineGroup **ppGroup );
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.
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.
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.
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.
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.
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.
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.
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.
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.
Not supported.
Syntax
HRESULT GetTimelineNoRef( IAMTimeline **ppResult );
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.
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.
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.
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.
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.
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.
Not implemented.
Syntax
HRESULT SetDirtyRange( REFERENCE_TIME Start, REFERENCE_TIME Stop );
Not implemented.
Syntax
HRESULT SetDirtyRange2( REFTIME Start, REFTIME Stop );
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.
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.
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.
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_OK Success. E_INVALIDARG Invalid argument. E_NOTIMPL Not 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.
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_OK Success. E_INVALIDARG Invalid argument. E_NOTIMPL Not implemented.
Not supported.
Syntax
HRESULT SetSubObject( IUnknown *newVal );
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.
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.
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 );
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.
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.
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.