Microsoft DirectX 8.0

RenderEngine Object

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

CommitNot supported for Visual Basic.
ConnectFrontEndBuilds the front end of the filter graph from the current timeline.
DecommitNot supported for Visual Basic.
DoSmartRecompressionNot supported for Visual Basic.
GetCapsNot supported for Visual Basic.
GetFilterGraphRetrieves the filter graph that the render engine has constructed, if any.
GetGroupOutputPinRetrieves the output pin for the specified group.
GetTimelineObjectRetrieves the timeline that the render engine is currently using.
GetVendorStringRetrieves the vendor string.
RenderOutputPinsCreates the previewing portion of the filter graph.
SetDynamicReconnectLevelSets the level of dynamic reconnection during rendering.
SetFilterGraphSpecifies a filter graph for the render engine to use.
SetInterestRangeNot supported for Visual Basic.
SetInterestRange2Not supported for Visual Basic.
SetRenderRangeNot supported for Visual Basic.
SetRenderRange2Sets the range of time on the timeline to be rendered.
SetSourceConnectCallbackNot supported for Visual Basic.
SetSourceNameValidationSpecifies how the render engine validates file names.
SetTimelineObjectSets the timeline for the render engine to use.
ScrapItDiscards the render engine's filter graph and all associated objects.
UseInSmartRecompressionGraphNot supported for Visual Basic.

Commit Method (RenderEngine Object)

RenderEngine Object

Not supported for Visual Basic.

Syntax

object.Commit()

ConnectFrontEnd (RenderEngine Object)

RenderEngine Object

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_INVALIDARGNo timeline set for this render engine.
E_MUST_INIT_RENDERERRender engine failed to initialize.
E_RENDER_ENGINE_IS_BROKENOperation failed because the project was not rendered successfully.
E_UNEXPECTEDUnexpected error.
VFW_E_INVALIDMEDIATYPEInvalid 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:

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.

Decommit (RenderEngine Object)

RenderEngine Object

Not supported for Visual Basic.

Syntax

object.Decommit()

DoSmartRecompression (RenderEngine Object)

RenderEngine Object

Not supported for Visual Basic.

Syntax

object.DoSmartRecompression()

GetCaps (RenderEngine Object)

RenderEngine Object

Not supported for Visual Basic.

Syntax

object.GetCaps(
    Index As Long,
    pReturn As Long
)

GetFilterGraph (RenderEngine Object)

RenderEngine Object

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_RENDERERRender engine failed to initialize.

GetGroupOutputPin (RenderEngine Object)

RenderEngine Object

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_INVALIDARGInvalid argument.
E_MUST_INIT_RENDERERRender engine failed to initialize.
E_RENDER_ENGINE_IS_BROKENOperation failed because project was not rendered successfully.
E_UNEXPECTEDUnexpected 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.

GetTimelineObject (RenderEngine Object)

RenderEngine Object

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_RENDERERRender engine failed to initialize.

GetVendorString (RenderEngine Object)

RenderEngine Object

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.

RenderOutputPins (RenderEngine Object)

RenderEngine Object

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_INVALIDARGInvalid argument.
E_RENDER_ENGINE_IS_BROKEN Operation failed because project was not rendered successfully.
E_UNEXPECTEDUnexpected 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.

ScrapIt (RenderEngine Object)

RenderEngine Object

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_RENDERERRender engine failed to initialize.

SetDynamicReconnectLevel (RenderEngine Object)

RenderEngine Object

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_NOTIMPLNot 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.

SetFilterGraph (RenderEngine Object)

RenderEngine Object

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_INVALIDARGInvalid argument.
E_MUST_INIT_RENDERERRender 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.

SetInterestRange (RenderEngine Object)

RenderEngine Object

Not supported for Visual Basic.

Syntax

object.SetInterestRange(
    Start As <Unsupported variant type>,
    Stop As <Unsupported variant type>
)

SetInterestRange2 (RenderEngine Object)

RenderEngine Object

Not supported for Visual Basic.

Syntax

object.SetInterestRange2(
    double Start As Double,
    double Stop As Double
)

SetRenderRange (RenderEngine Object)

RenderEngine Object

Not supported for Visual Basic.

Syntax

object.SetRenderRange(
    Start As <Unsupported variant type>,
    Stop As <Unsupported variant type>
)

SetRenderRange2 (RenderEngine Object)

RenderEngine Object

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_RENDERERRender engine failed to initialize.

SetSourceConnectCallback (RenderEngine Object)

RenderEngine Object

Not supported for Visual Basic.

Syntax

object.SetSourceConnectCallback(
    pCallback As IGrfCache
)

SetSourceNameValidation (RenderEngine Object)

RenderEngine Object

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_RENDERERRender 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.

SetTimelineObject (RenderEngine Object)

RenderEngine Object

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_RENDERERRender engine failed to initialize.
E_OUTOFMEMORYInsufficient memory.

UseInSmartRecompressionGraph (RenderEngine Object)

RenderEngine Object

Not supported for Visual Basic.

Syntax

object.UseInSmartRecompressionGraph()