Microsoft DirectX 8.0

IRenderEngine Interface

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 methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IRenderEngine MethodsDescription
SetTimelineObjectSets the timeline for the render engine to use.
GetTimelineObjectRetrieves the timeline that the render engine is currently using.
GetFilterGraphRetrieves the filter graph that the render engine has constructed, if any.
SetFilterGraphSpecifies a filter graph for the render engine to use.
SetInterestRangeNot supported.
SetInterestRange2Not supported.
SetRenderRangeSets the range of time on the timeline to be rendered.
SetRenderRange2Equivalent to SetRenderRange, but takes values of type double.
GetGroupOutputPinRetrieves the output pin for the specified group.
ScrapItDiscards the render engine's filter graph and all associated objects.
RenderOutputPinsCreates the previewing portion of the filter graph.
GetVendorStringRetrieves the vendor string.
ConnectFrontEndBuilds the front end of the filter graph from the current timeline.
SetSourceConnectCallbackNot supported.
SetDynamicReconnectLevelSets the level of dynamic reconnection during rendering.
DoSmartRecompressionNot supported.
UseInSmartRecompressionGraphNot supported.
SetSourceNameValidationSpecifies how the render engine validates file names.
CommitNot implemented.
DecommitNot implemented.
GetCapsNot implemented.

IRenderEngine::Commit

IRenderEngine Interface

Not implemented.

Syntax

HRESULT Commit( void );

IRenderEngine::ConnectFrontEnd

IRenderEngine Interface

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_OKSuccess.
S_WARN_OUTPUTRESETRendering portion of the graph was deleted.
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 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.

IRenderEngine::Decommit

IRenderEngine Interface

Not implemented.

Syntax

HRESULT Decommit( void );

IRenderEngine::DoSmartRecompression

IRenderEngine Interface

Not supported.

Syntax

HRESULT DoSmartRecompression( void );

IRenderEngine::GetCaps

IRenderEngine Interface

Not implemented.

Syntax

HRESULT GetCaps(
    long Index,
    long *pReturn
);

IRenderEngine::GetFilterGraph

IRenderEngine Interface

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_OKSuccess.
E_MUST_INIT_RENDERERRender engine failed to initialize.
E_POINTERInvalid 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.

IRenderEngine::GetGroupOutputPin

IRenderEngine Interface

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_FALSEGroup does not have an output pin.
S_OKSuccess.
E_INVALIDARGInvalid argument.
E_MUST_INIT_RENDERERRender engine failed to initialize.
E_POINTERInvalid pointer.
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.

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.

IRenderEngine::GetTimelineObject

IRenderEngine Interface

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_OKSuccess.
E_POINTERInvalid pointer.
E_MUST_INIT_RENDERERRender 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.

IRenderEngine::GetVendorString

IRenderEngine Interface

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.

IRenderEngine::RenderOutputPins

IRenderEngine Interface

Creates the previewing portion of the filter graph.

Syntax

HRESULT RenderOutputPins( void );

Return Value

Returns an HRESULT values. The following are possible values:

S_OKSuccess.
VFW_S_AUDIO_NOT_RENDEREDCannot play back the audio stream.
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.

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 messages—for example, to move the window, or respond to mouse clicks in the window's client area.

IRenderEngine::ScrapIt

IRenderEngine Interface

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

IRenderEngine::SetDynamicReconnectLevel

IRenderEngine Interface

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_OKSuccess.
E_NOTIMPLNot 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.

IRenderEngine::SetFilterGraph

IRenderEngine Interface

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

IRenderEngine::SetInterestRange

IRenderEngine Interface

Not supported.

Syntax

HRESULT SetInterestRange(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

IRenderEngine::SetInterestRange2

IRenderEngine Interface

Not supported.

Syntax

HRESULT SetInterestRange2(
    double Start,
    double Stop
);

IRenderEngine::SetRenderRange

IRenderEngine Interface

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

IRenderEngine::SetRenderRange2

IRenderEngine Interface

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

IRenderEngine::SetSourceConnectCallback

IRenderEngine Interface

Not supported.

Syntax

HRESULT SetSourceConnectCallback(
    IGrfCache *pCallback
);

IRenderEngine::SetSourceNameValidation

IRenderEngine Interface

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_OKSuccess.
E_MUST_INIT_RENDERERRender 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.

IRenderEngine::SetTimelineObject

IRenderEngine Interface

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_OKSuccess.
E_MUST_INIT_RENDERERRender engine failed to initialize.
E_OUTOFMEMORYInsufficient memory.
E_POINTERInvalid pointer.

IRenderEngine::UseInSmartRecompressionGraph

IRenderEngine Interface

Not supported.

Syntax

HRESULT UseInSmartRecompressionGraph( void );