Microsoft DirectX 8.0 |
Renders a Microsoft® DirectShow® Editing Services (DES) project by constructing a filter graph from a timeline.
DES provides two components that implement this interface:
The smart render engine also supports the ISmartRenderEngine interface.
Although an application can create a filter graph and pass it to a render engine, the typical scenario is for the render engine to create the filter graph. Building the graph is a two-stage process. First, build the front end by calling the ConnectFrontEnd method. Then connect the output pins on the front end to the desired rendering filters:
For more information, see Rendering a Project.
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. IRenderEngine Methods Description SetTimelineObject Sets the timeline for the render engine to use. GetTimelineObject Retrieves the timeline that the render engine is currently using. GetFilterGraph Retrieves the filter graph that the render engine has constructed, if any. SetFilterGraph Specifies a filter graph for the render engine to use. SetInterestRange Not supported. SetInterestRange2 Not supported. SetRenderRange Sets the range of time on the timeline to be rendered. SetRenderRange2 Equivalent to SetRenderRange, but takes values of type double. GetGroupOutputPin Retrieves the output pin for the specified group. ScrapIt Discards the render engine's filter graph and all associated objects. RenderOutputPins Creates the previewing portion of the filter graph. GetVendorString Retrieves the vendor string. ConnectFrontEnd Builds the front end of the filter graph from the current timeline. SetSourceConnectCallback Not supported. SetDynamicReconnectLevel Sets the level of dynamic reconnection during rendering. DoSmartRecompression Not supported. UseInSmartRecompressionGraph Not supported. SetSourceNameValidation Specifies how the render engine validates file names. Commit Not implemented. Decommit Not implemented. GetCaps Not implemented.
Not implemented.
Syntax
HRESULT Commit( void );
Builds the front end of the filter graph from the current timeline.
Syntax
HRESULT ConnectFrontEnd( void );
Return Value
Returns an HRESULT value. Possible return values include the following:
S_OK Success. S_WARN_OUTPUTRESET Rendering portion of the graph was deleted. E_INVALIDARG No timeline set for this render engine. E_MUST_INIT_RENDERER Render engine failed to initialize. E_RENDER_ENGINE_IS_BROKEN Operation failed because the project was not rendered successfully. E_UNEXPECTED Unexpected error. VFW_E_INVALIDMEDIATYPE Invalid media type.
Remarks
This method does not build the rendering portion of the filter graph. The application must connect the output pins on the front end to the desired rendering filters:
- To preview, call the RenderOutputPins method.
- To output a file, call GetGroupOutputPin to retrieve the output pin for each group, then connect the pins to a multiplexer filter.
If you are using the basic render engine, the output pins on the front end produce uncompressed data. If you are using the smart render engine, the output pins produce compressed data.
If you change the timeline after you build the filter graph, you must call ConnectFrontEnd again to rebuild the front end. The method preserves the rendering portion of the graph whenever possible. However, if you add or delete a group, or change the order of the groups, ConnectFrontEnd deletes the rendering portion and your application must rebuild it. If the method deletes the rendering portion, it returns S_WARN_OUTPUTRESET.
Not implemented.
Syntax
HRESULT Decommit( void );
Not supported.
Syntax
HRESULT DoSmartRecompression( void );
Not implemented.
Syntax
HRESULT GetCaps( long Index, long *pReturn );
Retrieves the filter graph that the render engine has constructed, if any.
Syntax
HRESULT GetFilterGraph( IGraphBuilder **ppFG );
Parameters
- ppFG
- [out] Address of a pointer to receive the filter graph's IGraphBuilder interface. It receives the value NULL if there is no filter graph.
Return Value
Returns one of the following HRESULT values:
S_OK Success. E_MUST_INIT_RENDERER Render engine failed to initialize. E_POINTER Invalid pointer.
Remarks
On return, if the value of *ppFG is non-NULL, the IGraphBuilder interface has an outstanding reference count. Be sure to release the interface when you are finished using it.
Retrieves the output pin for the specified group.
Syntax
HRESULT GetGroupOutputPin( long Group, IPin **ppRenderPin );
Parameters
- Group
- Zero-based index that specifies the group.
- ppRenderPin
- [out] Address of a pointer to receive the output pin's IPin interface.
Return Value
Returns an HRESULT value. Possible values include the following:
S_FALSE Group does not have an output pin. S_OK Success. E_INVALIDARG Invalid argument. E_MUST_INIT_RENDERER Render engine failed to initialize. E_POINTER Invalid pointer. E_RENDER_ENGINE_IS_BROKEN Operation failed because project was not rendered successfully. E_UNEXPECTED Unexpected error.
Remarks
Before calling this method, call ConnectFrontEnd to build the front end of the graph. Each group represents a single media stream, and the front end has a corresponding output pin.
You can use this method to create the rendering portion of a file-writing graph. Connect the output pins to multiplexer filters and file writer filters. For more information, see Rendering a Project.
For preview, you don't need to call this method. Just call ConnectFrontEnd followed by RenderOutputPins.
If the method returns S_OK, the IPin interface that it returns has an outstanding reference count. Be sure to release the interface when you are finished using it.
Retrieves the timeline that the render engine is currently using.
Syntax
HRESULT GetTimelineObject( IAMTimeline **ppTimeline );
Parameters
- ppTimeline
- [out] Address of a pointer to receive the timeline's IAMTimeline interface. It receives the value NULL if there is no timeline.
Return Value
Returns one of the following HRESULT values:
S_OK Success. E_POINTER Invalid pointer. E_MUST_INIT_RENDERER Render engine failed to initialize.
Remarks
On return, if the value of *ppTimeline is non-NULL, the IAMTimeline interface has an outstanding reference count. Be sure to release the interface when you are finished using it.
Retrieves the vendor string.
Syntax
HRESULT GetVendorString( BSTR *pVendorID );
Parameters
- pVendorID
- [out, retval] Pointer to a variable that receives a BSTR containing the vendor string.
Return Value
Returns S_OK if the method succeeds. Otherwise, returns an 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.
Creates the previewing portion of the filter graph.
Syntax
HRESULT RenderOutputPins( void );
Return Value
Returns an HRESULT values. The following are possible values:
S_OK Success. VFW_S_AUDIO_NOT_RENDERED Cannot play back the audio stream. E_INVALIDARG Invalid argument. E_RENDER_ENGINE_IS_BROKEN Operation failed because project was not rendered successfully. E_UNEXPECTED Unexpected error.
Remarks
Before calling this method, call ConnectFrontEnd to build the front end of the graph. To perform an operation other than preview, do not call this method. Instead, call GetGroupOutputPin to obtain pointers to the output pins.
If there is no sound card on the user's computer, this method returns VFW_S_AUDIO_NOT_RENDERED. There will not be audio preview in this case, but video preview is unaffected.
If the pin is from a video group, this method creates a video window. The calling thread must dispatch messagesfor example, to move the window, or respond to mouse clicks in the window's client area.
Discards the render engine's filter graph and all associated objects.
Syntax
HRESULT ScrapIt( void );
Return Value
Returns one of the following HRESULT values:
S_OK Success. E_MUST_INIT_RENDERER Render engine failed to initialize.
Sets the level of dynamic reconnection during rendering.
Syntax
HRESULT SetDynamicReconnectLevel( DWORD Level );
Parameters
- Level
- Combination of Dynamic Reconnection Flags, specifying the level of dynamic reconnection.
Return Value
Returns one of the following HRESULT values:
S_OK Success. E_NOTIMPL Not implemented.
Remarks
By default, the basic render engine loads every source before rendering a project. This can result in a long start-up time. With dynamic reconnection, sources are loaded only when needed. This can shorten the start-up time, but possibly interfere with smooth playback. Generally, the more source clips that a project uses, the more you might benefit from dynamic reconnection.
The smart render engine does not implement this method.
Specifies a filter graph for the render engine to use.
Syntax
HRESULT SetFilterGraph( IGraphBuilder *pFG );
Parameters
- pFG
- Pointer to the IGraphBuilder interface of the filter graph.
Return Value
Returns one of the following HRESULT values:
S_OK Success. E_INVALIDARG Invalid argument. E_MUST_INIT_RENDERER Render engine failed to initialize.
Remarks
Most applications do not need to call this method. It is more typical to let the render engine build the graph for you, by calling the ConnectFrontEnd method.
This method fails if the render engine already has a filter graph.
Never retrieve a pointer to a filter graph created by one render engine and then use it as the parameter to this method on another render engine. Doing so will cause unpredictable results.
Not supported.
Syntax
HRESULT SetInterestRange( REFERENCE_TIME Start, REFERENCE_TIME Stop );
Not supported.
Syntax
HRESULT SetInterestRange2( double Start, double Stop );
Sets the range of time on the timeline to be rendered. Objects that lie outside the specified range are not rendered, and resources are not allocated for them.
Syntax
HRESULT SetRenderRange( REFERENCE_TIME Start, REFERENCE_TIME Stop );
Parameters
- Start
- Start time, in 100-nanosecond units.
- Stop
- Stop time, in 100-nanosecond units.
Return Value
Returns one of the following HRESULT values:
S_OK Success. E_MUST_INIT_RENDERER Render engine failed to initialize.
Sets the range of time on the timeline to be rendered. This method is equivalent to SetRenderRange, but takes values of type double.
Syntax
HRESULT SetRenderRange2( double Start, double Stop );
Parameters
- Start
- Start time, in seconds.
- Stop
- Stop time, in seconds.
Return Value
Returns one of the following HRESULT values:
S_OK Success. E_MUST_INIT_RENDERER Render engine failed to initialize.
Not supported.
Syntax
HRESULT SetSourceConnectCallback( IGrfCache *pCallback );
Specifies how the render engine validates file names.
Syntax
HRESULT SetSourceNameValidation( BSTR FilterString, IMediaLocator *pOverride, LONG Flags );
Parameters
- FilterString
- BSTR value containing pairs of filter strings, formatted as required by the lpstrFilter member of the Microsoft® Win32® OPENFILENAME structure. The media locator uses this filter if it presents an Open File dialog box to the end user.
- pOverride
- Optional pointer to the IMediaLocator interface of a media locator to use in place of the default. To use the default media locator, set the value of this parameter to NULL. See Remarks for more information.
- Flags
- Bitwise combination of flags specifying the behavior of the media locator. The SFN_VALIDATEF_CHECK flag must be present. The SFN_VALIDATEF_IGNOREMUTED flag has no effect with this method.
Return Value
Returns one of the following HRESULT values:
S_OK Success. E_MUST_INIT_RENDERER Render engine failed to initialize.
Remarks
Using the pOverride parameter, you can supply your own custom implementation of the IMediaLocator interface. For example, the default media locator does not notify an application about the files that it finds (or cannot find). To get around this limitation, you could implement a custom media locator, making it a wrapper for the default version. Then pass IMediaLocator::FindMediaFile calls directly to the default version and examine the return value.
Currently, this method does not validate dynamically loaded sources. See SetDynamicReconnectLevel.
Sets the timeline for the render engine to use.
Syntax
HRESULT SetTimelineObject( IAMTimeline *pTimeline );
Parameters
- pTimeline
- Pointer to the timeline object's IAMTimeline interface.
Return Value
Returns one of the following HRESULT values:
S_OK Success. E_MUST_INIT_RENDERER Render engine failed to initialize. E_OUTOFMEMORY Insufficient memory. E_POINTER Invalid pointer.
Not supported.
Syntax
HRESULT UseInSmartRecompressionGraph( void );