Microsoft DirectX 8.0 |
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 methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IAMTimelineGroup Methods Description SetTimeline Not supported. GetTimeline Retrieves the timeline to which this group belongs. GetPriority Retrieves the group's priority. GetMediaType Retrieves the uncompressed media type for the group. SetMediaType Sets the uncompressed media type for the group. SetOutputFPS Sets the uncompressed output frame rate for this group. GetOutputFPS Retrieves the output frame rate of this group. SetGroupName Sets the application-defined name of the group. GetGroupName Retrieves the application-defined name of the group. SetPreviewMode Sets the preview mode for the group. GetPreviewMode Retrieves the preview mode for the group. SetMediaTypeForVB Specifies the group media type, for Automation clients. GetOutputBuffering Retrieves the number of frames rendered in advance during preview. SetOutputBuffering Specifies the number of frames rendered in advance during preview. SetSmartRecompressFormat Specifies a compression format to use for smart recompression. GetSmartRecompressFormat Retrieves the current compression format for smart recompression. IsSmartRecompressFormatSet Determines whether a smart compression format was set for the group. IsRecompressFormatDirty Not supported. ClearRecompressFormatDirty Not supported. SetRecompFormatFromSource Sets the video recompression format using the compression format from a source file.
Not supported.
Syntax
HRESULT ClearRecompressFormatDirty(void);
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.
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.
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.
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.
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.
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.
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.
if successful, or E_POINTER otherwise.
S_OK Success. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL pointer argument.
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; }
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.
Not supported.
Syntax
HRESULT IsRecompressFormatDirty( BOOL *pVal );
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.
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.
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_OK Success. E_POINTER NULL pointer argument. VFW_E_INVALIDMEDIATYPE The specified media type is invalid.
Remarks
Currently, the following media types are supported:
- Uncompressed RGB video
- 16 bits per pixel, 555 format
- 24 bits per pixel
- 32 bits per pixel
- 16-bit stereo PCM audio
To specify a compression format for the group, call the SetSmartRecompressFormat method.
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.
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.
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.
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.
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_OK Success. E_NO_TIMELINE The group is not within a timeline. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL pointer argument. VFW_E_INVALIDMEDIATYPE Invalid 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.
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_OK Success. E_POINTER NULL pointer argument. E_INVALIDARG Invalid 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.
Not supported. Call the IAMTimeline::AddGroup method instead.
Syntax
HRESULT SetTimeline( IAMTimeline *pTimeline );