Microsoft DirectX 8.0

IAMTimelineGroup Interface

Sets and retrieves properties on groups in Microsoft® DirectShow® Editing Services (DES).

A group contains one or more tracks, and possibly one or more compositions, which in turn contain source clips of a uniform type, such as video or audio. Groups are the topmost compositions in a timeline, and also expose the IAMTimelineComp interface. A timeline can contain multiple groups.

Each group has the following attributes.

Requirements

Requires Qedit.h.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IAMTimelineGroup MethodsDescription
SetTimelineNot supported.
GetTimelineRetrieves the timeline to which this group belongs.
GetPriorityRetrieves the group's priority.
GetMediaTypeRetrieves the uncompressed media type for the group.
SetMediaTypeSets the uncompressed media type for the group.
SetOutputFPSSets the uncompressed output frame rate for this group.
GetOutputFPSRetrieves the output frame rate of this group.
SetGroupNameSets the application-defined name of the group.
GetGroupNameRetrieves the application-defined name of the group.
SetPreviewModeSets the preview mode for the group.
GetPreviewModeRetrieves the preview mode for the group.
SetMediaTypeForVBSpecifies the group media type, for Automation clients.
GetOutputBufferingRetrieves the number of frames rendered in advance during preview.
SetOutputBufferingSpecifies the number of frames rendered in advance during preview.
SetSmartRecompressFormatSpecifies a compression format to use for smart recompression.
GetSmartRecompressFormatRetrieves the current compression format for smart recompression.
IsSmartRecompressFormatSetDetermines whether a smart compression format was set for the group.
IsRecompressFormatDirtyNot supported.
ClearRecompressFormatDirtyNot supported.
SetRecompFormatFromSourceSets the video recompression format using the compression format from a source file.

IAMTimelineGroup::ClearRecompressFormatDirty

IAMTimelineGroup Interface

Not supported.

Syntax

HRESULT ClearRecompressFormatDirty(void);

IAMTimelineGroup::GetGroupName

IAMTimelineGroup Interface

Retrieves the application-defined name of the group.

Syntax

HRESULT GetGroupName(
    BSTR *pGroupName
);

Parameters

pGroupName
[out, retval] Pointer to a variable of type BSTR that receives the name of the group.

Return Value

Returns S_OK if successful. Otherwise, returns E_POINTER 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.

IAMTimelineGroup::GetMediaType

IAMTimelineGroup Interface

Retrieves the uncompressed media type for the group.

Syntax

HRESULT GetMediaType(
    AM_MEDIA_TYPE *pmt
);

Parameters

pmt
[out] Pointer to an AM_MEDIA_TYPE structure that is filled with the media type.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineGroup::GetOutputBuffering

IAMTimelineGroup Interface

Retrieves the number of frames rendered in advance during preview.

Syntax

HRESULT GetOutputBuffering(
    int *pnBuffer
);

Parameters

pnBuffer
[out] Pointer to a variable that receives the number of buffered frames.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineGroup::GetOutputFPS

IAMTimelineGroup Interface

Retrieves the output frame rate of this group.

Syntax

HRESULT GetOutputFPS(
    double *pFPS
);

Parameters

pFPS
Pointer to a variable that receives the output frame rate, in frames per second.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineGroup::GetPreviewMode

IAMTimelineGroup Interface

Retrieves the preview mode for the group.

Syntax

HRESULT GetPreviewMode(
    BOOL *pfPreview
);

Parameters

pfPreview
Pointer to a variable that receives a Boolean value indicating the preview mode. If TRUE, the group is in preview mode. If FALSE, the group is in authoring mode.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

Remarks

In preview mode, frames are dropped during slow effects or transitions to keep the video synchronized with the audio. The video might look choppy as a result. In authoring mode, every frame is rendered. Authoring mode is appropriate for writing files; for on-screen preview, the video might become out of sync with the audio.

IAMTimelineGroup::GetPriority

IAMTimelineGroup Interface

Retrieves the group's priority.

Syntax

HRESULT GetPriority(
    long *pPriority
);

Parameters

pPriority
Pointer to a variable that receives the group's priority.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineGroup::GetSmartRecompressFormat

IAMTimelineGroup Interface

Retrieves the current compression format for smart recompression.

Syntax

HRESULT GetSmartRecompressFormat(
   long **ppFormat
);

Parameters

ppFormat
Address of a variable that receives a pointer to an SCompFmt0 structure, cast as a pointer to a long. If the method fails, the value is set to NULL.

Return Value

Returns an HRESULT value. Possible values include the following.
S_OKSuccess.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL pointer argument.
if successful, or E_POINTER otherwise.

Remarks

If the application has not set a smart compression format (by calling SetSmartRecompressFormat), the format returned by this method will be invalid. Call the IsSmartRecompressFormatSet method to determine whether a compression format was set.

If the method succeeds, the caller must free the returned media type and delete the SCompFmt0 structure:

if (pFormat) {
    FreeMediaType(pFormat->MediaType);
    delete pFormat;
}

IAMTimelineGroup::GetTimeline

IAMTimelineGroup Interface

Retrieves the timeline to which this group belongs.

Syntax

HRESULT GetTimeline(
    IAMTimeline **ppTimeline
);

Parameters

ppTimeline
[out] Address of a pointer that receives the timeline's IAMTimeline interface. If the group is not part of a timeline, the value is set to NULL.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

Remarks

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

IAMTimelineGroup::IsRecompressFormatDirty

IAMTimelineGroup Interface

Not supported.

Syntax

HRESULT IsRecompressFormatDirty(
    BOOL *pVal
);

IAMTimelineGroup::IsSmartRecompressFormatSet

IAMTimelineGroup Interface

Determines whether a smart recompression format was set for the group.

Syntax

HRESULT IsSmartRecompressFormatSet(
    BOOL *pVal
);

Parameters

pVal
Pointer to a variable that receives a Boolean value indicating whether a compression format was set. If TRUE, a compression format was set.

Return Value

Returns S_OK if successful, or E_POINTER otherwise.

IAMTimelineGroup::SetGroupName

IAMTimelineGroup Interface

Sets the application-defined name of the group.

Syntax

HRESULT SetGroupName(
    BSTR pGroupName
);

Parameters

pGroupName
BSTR that specifies the name of the group.

Return Value

Returns S_OK.

IAMTimelineGroup::SetMediaType

IAMTimelineGroup Interface

Sets the uncompressed media type for the group.

Syntax

HRESULT SetMediaType(
    AM_MEDIA_TYPE *pmt
);

Parameters

pmt
[in] Pointer to an AM_MEDIA_TYPE structure describing the format.

Return Value

Returns one of the following HRESULT values:

S_OKSuccess.
E_POINTERNULL pointer argument.
VFW_E_INVALIDMEDIATYPEThe specified media type is invalid.

Remarks

Currently, the following media types are supported:

To specify a compression format for the group, call the SetSmartRecompressFormat method.

IAMTimelineGroup::SetMediaTypeForVB

IAMTimelineGroup Interface

Specifies the group media type, for Automation clients.

Syntax

HRESULT SetMediaTypeForVB(
    long Val
);

Parameters

Val
[in] Value that specifies the media type. Set the value to 0 for video, or 1 for audio.

Return Value

Returns S_OK.

Remarks

This method is intended for Automation clients. For C++ applications, use the SetMediaType method.

IAMTimelineGroup::SetOutputBuffering

IAMTimelineGroup Interface

Specifies the number of frames rendered in advance during preview.

Syntax

HRESULT SetOutputBuffering(
    int nBuffer
);

Parameters

nBuffer
[in] Number of frames to buffer during preview. Must be two or greater.

Return Value

Returns S_OK if successful, or E_INVALIDARG otherwise.

Remarks

A larger buffer requires more memory but can result in smoother previewing, especially during effects or transitions that require more time to render. The default buffer is 30 frames.

IAMTimelineGroup::SetOutputFPS

IAMTimelineGroup Interface

Sets the uncompressed output frame rate for this group.

Syntax

HRESULT SetOutputFPS(
    double FPS
);

Parameters

FPS
Output frame rate for this group, in frames per second. The value cannot equal zero, and cannot have more than seven digits after the decimal place.

Return Value

Returns S_OK if successful, or E_INVALIDARG otherwise.

Remarks

Rendered output from this group runs at the specified frame rate, and all edits on the source material are rounded to the nearest frame boundary, as defined by the frame rate.

The SetSmartRecompressFormat method overwrites the frame rate.

IAMTimelineGroup::SetPreviewMode

IAMTimelineGroup Interface

Sets the preview mode for the group.

Syntax

HRESULT SetPreviewMode(
    BOOL fPreview
);

Parameters

fPreview
Boolean value that specifies the preview mode. If TRUE, the group is in preview mode. If FALSE, the group is in authoring mode.

Return Value

Returns S_OK.

Remarks

In preview mode, frames are dropped during slow effects or transitions to keep the video synchronized with the audio. The video might look choppy as a result. In authoring mode, every frame is rendered. Authoring mode is appropriate for writing files; for on-screen preview, the video might be out of sync with the audio.

IAMTimelineGroup::SetRecompFormatFromSource

IAMTimelineGroup Interface

Sets the video recompression format using the compression format from a source file.

Syntax

HRESULT SetRecompFormatFromSource( 
    IAMTimelineSrc *pSource 
);

Parameters

pSource
Pointer to the IAMTimelineSrc interface of the source object.

Return Value

Returns an HRESULT values. Possible values include the following.

S_OKSuccess.
E_NO_TIMELINEThe group is not within a timeline.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL pointer argument.
VFW_E_INVALIDMEDIATYPEInvalid media type. The group is not a video group, or the source file has no video stream.

Remarks

This method finds the source file associated with pSource, retrieves the media type of the first video stream in the file, and sets the group compression format using that type. For more information about compression formats, see SetSmartRecompressFormat.

IAMTimelineGroup::SetSmartRecompressFormat

IAMTimelineGroup Interface

Specifies a compression format to use for smart recompression.

Smart recompression is not supported for audio groups.

Syntax

HRESULT SetSmartRecompressFormat(
    long *pFormat
);

Parameters

pFormat
Pointer to a structure describing the compression format. Currently, only the SCompFmt0 structure is valid. You must cast this parameter to a pointer of type long.

Return Value

Returns one of the following HRESULT values:

S_OKSuccess.
E_POINTERNULL pointer argument.
E_INVALIDARGInvalid argument.

Remarks

Before calling this method, call the SetMediaType method on the same group, to specify an uncompressed format. The compressed and uncompressed formats must have the same width, height, and frame rate. If these values do not match, the group output pin produces uncompressed output instead of compressed output.

This method overwrites any frame rate value that was set using the SetOutputFPS method.

The smart recompression format is not persistent. If an application uses smart recompression, it must set the recompression format whenever it loads a project file.

IAMTimelineGroup::SetTimeline

IAMTimelineGroup Interface

Not supported. Call the IAMTimeline::AddGroup method instead.

Syntax

HRESULT SetTimeline(
    IAMTimeline *pTimeline
);