Microsoft DirectX 8.0 |
Renders a Microsoft® DirectShow® Editing Services (DES) project by constructing a filter graph from a timeline.
DES provides two objects that rendering timelines:
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:
Methods
Commit Not supported for Visual Basic. ConnectFrontEnd Builds the front end of the filter graph from the current timeline. Decommit Not supported for Visual Basic. DoSmartRecompression Not supported for Visual Basic. GetCaps Not supported for Visual Basic. GetFilterGraph Retrieves the filter graph that the render engine has constructed, if any. GetGroupOutputPin Retrieves the output pin for the specified group. GetTimelineObject Retrieves the timeline that the render engine is currently using. GetVendorString Retrieves the vendor string. RenderOutputPins Creates the previewing portion of the filter graph. SetDynamicReconnectLevel Sets the level of dynamic reconnection during rendering. SetFilterGraph Specifies a filter graph for the render engine to use. SetInterestRange Not supported for Visual Basic. SetInterestRange2 Not supported for Visual Basic. SetRenderRange Not supported for Visual Basic. SetRenderRange2 Sets the range of time on the timeline to be rendered. SetSourceConnectCallback Not supported for Visual Basic. SetSourceNameValidation Specifies how the render engine validates file names. SetTimelineObject Sets the timeline for the render engine to use. ScrapIt Discards the render engine's filter graph and all associated objects. UseInSmartRecompressionGraph Not supported for Visual Basic.
Not supported for Visual Basic.
Syntax
object.Commit()
Builds the front end of the filter graph from the current timeline.
Syntax
object.ConnectFrontEnd()
Parts
- object
- Object expression that evaluates to a RenderEngine object.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to one of the following values:
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 RenderEngine object, the output pins on the front end produce uncompressed data. If you are using the SmartRenderEngine object, 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.
Not supported for Visual Basic.
Syntax
object.Decommit()
Not supported for Visual Basic.
Syntax
object.DoSmartRecompression()
Not supported for Visual Basic.
Syntax
object.GetCaps( Index As Long, pReturn As Long )
Retrieves the filter graph that the render engine has constructed, if any.
Syntax
object.GetFilterGraph( ppFG As IGraphBuilder )
Parts
- object
- Object expression that evaluates to a RenderEngine object.
- ppFG
- The FilgraphManager object that receives the filter graph.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to the following value:
E_MUST_INIT_RENDERER Render engine failed to initialize.
Retrieves the output pin for the specified group.
Syntax
object.GetGroupOutputPin( Group As Long, ppRenderPin As IPin )
Parts
- object
- Object expression that evaluates to a RenderEngine object.
- Group
- Zero-based index that specifies the group.
- ppRenderPin
- The IPin object that receives the output pin.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to one of the following values:
E_INVALIDARG Invalid argument. E_MUST_INIT_RENDERER Render engine failed to initialize. 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.
Retrieves the timeline that the render engine is currently using.
Syntax
object.GetTimelineObject( ppTimeline As AMTimeline )
Parts
- object
- Object expression that evaluates to a RenderEngine object.
- ppTimeline
- The AMTimeline object that receives the timeline.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to the following value:
E_MUST_INIT_RENDERER Render engine failed to initialize.
Retrieves the vendor string.
Syntax
object.GetVendorString() As String
Parts
- object
- Object expression that evaluates to a RenderEngine object.
Return Value
Returns a string containing the vendor name.
Error Codes
If the method fails, an error is raised.
Creates the previewing portion of the filter graph.
Syntax
object.RenderOutputPins()
Parts
- object
- Object expression that evaluates to a RenderEngine object.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to one of the following values:
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.
Discards the render engine's filter graph and all associated objects.
Syntax
object.ScrapIt()
Parts
- object
- Object expression that evaluates to a RenderEngine object.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to the following value:
E_MUST_INIT_RENDERER Render engine failed to initialize.
Sets the level of dynamic reconnection during rendering.
Syntax
object.SetDynamicReconnectLevel( Level As Long )
Parts
- object
- Object expression that evaluates to a RenderEngine object.
- Level
- Bitwise combination of zero or more Dynamic Reconnection Flags, specifying the level of dynamic reconnection.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to the following value:
E_NOTIMPL Not implemented.
Remarks
By default, the RenderEngine object 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 SmartRenderEngine object does not implement this method.
Specifies a filter graph for the render engine to use.
Syntax
object.SetFilterGraph( pFG As IGraphBuilder )
Parts
- object
- Object expression that evaluates to a RenderEngine object.
- pFG
- The FilgraphManager object that specifies the filter graph.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to one of the following values:
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 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 for Visual Basic.
Syntax
object.SetInterestRange( Start As <Unsupported variant type>, Stop As <Unsupported variant type> )
Not supported for Visual Basic.
Syntax
object.SetInterestRange2( double Start As Double, double Stop As Double )
Not supported for Visual Basic.
Syntax
object.SetRenderRange( Start As <Unsupported variant type>, Stop As <Unsupported variant type> )
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
object.SetRenderRange2( Start As Double, Stop As Double )
Parts
- object
- Object expression that evaluates to a RenderEngine object.
- Start
- Start time, in seconds.
- Stop
- Stop time, in seconds.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to the following value:
E_MUST_INIT_RENDERER Render engine failed to initialize.
Not supported for Visual Basic.
Syntax
object.SetSourceConnectCallback( pCallback As IGrfCache )
Specifies how the render engine validates file names.
Syntax
object.SetSourceNameValidation( FilterString As String, pOverride As MediaLocator, Flags As Long )
Parts
- object
- Object expression that evaluates to a RenderEngine object.
- FilterString
- String 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 displays an Open dialog box.
- pOverride
- Optional MediaLocator object 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 MediaLocator object. The SFN_VALIDATEF_CHECK flag must be present. The SFN_VALIDATEF_IGNOREMUTED flag has no effect with this method.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to the following value:
E_MUST_INIT_RENDERER Render engine failed to initialize.
Remarks
Using the pOverride parameter, you can supply your own custom implementation of the MediaLocator object.
Currently, this method does not validate dynamically loaded sources. See SetDynamicReconnectLevel.
Sets the timeline for the render engine to use.
Syntax
object.SetTimelineObject( pTimeline As AMTimeline )
Parts
- object
- Object expression that evaluates to a RenderEngine object.
- pTimeline
- An AMTimeline object that specifies the timeline.
Error Codes
If the method fails, an error is raised, and Err.Number can be set to one of the following values:
E_MUST_INIT_RENDERER Render engine failed to initialize. E_OUTOFMEMORY Insufficient memory.
Not supported for Visual Basic.
Syntax
object.UseInSmartRecompressionGraph()