Search this site

ViERender

Contents

  1. 1 Class ExternalRenderer
  2. 2 ExternalRenderer::FrameSizeChange
  3. 3 ExternalRenderer::DeliverFrame
  4. 4 GetInterface
  5. 5 Release
  6. 6 RegisterVideoRenderModule
  7. 7 DeRegisterVideoRenderModule
  8. 8 AddRenderer
  9. 9 RemoveRenderer
  10. 10 StartRender
  11. 11 StopRender
  12. 12 ConfigureRender
  13. 13 MirrorRenderStream
  14. 14 AddRenderer

The ViERender API is used for

  • Specify render destinations for incoming video streams, capture devices and files.

  • Configuring render streams.

NOTE: The ViERender:: prefix is excluded for most API names throughout this chapter.

Class ExternalRenderer

This class declares an abstract interface to be used for external renderers. The user implemented derived class is registered using AddRenderer().

NOTE: Always ensure that the callback functions are kept as short as possible to ensure that additional callbacks are not delayed.

class ExternalRenderer

{

public:

    virtual int FrameSizeChange(unsigned int width,

                                              unsigned int height,

                                              unsigned int numberOfStreams);

    virtual int DeliverFrame(unsigned char* buffer, int bufferSize,

                                        unsigned int time_stamp);

};

ExternalRenderer::FrameSizeChange

This method will be called when the stream to be rendered changes in resolution or number of streams mixed in the image.

Syntax

int FrameSizeChange(unsigned int width, unsigned int height, unsigned int numberOfStreams);

Parameters

width [in] Resolution width of the video frames, in number of pixels.

height [in] Resolution height of the video frames, in number of pixels.

numberOfStreams [in] The number of streams in the video stream.

Remarks

This function is called as soon as the stream configuration changes.

numberOfStreams can be used for demuxing purposes.

ExternalRenderer::DeliverFrame

This method is called when a new frame should be rendered.

Syntax

int DeliverFrame(unsigned char* buffer, int bufferSize);

Parameters

buffer [in] A pointer to the buffer containing the I420 video frame.

bufferSize [in] Size of the video frame, in number of bytes.

time_stamp [in] Time stamp of the video frame in 90kHz.

Remarks

The video frame is always delivered as an I420 and should be rendered on screen as soon as possible.

GetInterface

Retrieves a pointer to the ViERender sub-API and increases an internal reference counter for this sub API.

Syntax

static ViERender* GetInterface(VideoEngine* videoEngine);

Parameters

videoEngine [in] Pointer to an already created VideoEngine object.

Return Values

If the function succeeds, the return value is a pointer to the new ViERender interface.

If the function fails, the return value is NULL.

Remarks

See VideoEngine::Create() for details on how to create the VideoEngine object.

Each call to this function increments an internal reference counter for the specified VideoEngine object. This reference count is decreased by calling the corresponding Release() method and it must be zero when the VideoEngine instance is deleted (see also VideoEngine::Delete()).

Requirements

Supported platforms

Windows, Mac OS X, Linux

Header

Declared in vie_render.h

Release

Releases the ViERender sub-API and decreases the internal reference counter for this sub-API.

Syntax

int Release();

Return Values

If the function succeeds, the return value is the value of the internal reference count.

If the function fails, the return value is -1.

Remarks

The number of calls to Release() should always match the number of calls to GetInterface() for the sub-API. VideoEngine::Delete() will fail if the internal reference count is non-zero.

Requirements

Supported platforms

Windows, Mac OS X, Linux

Header

Declared in vie_render.h

RegisterVideoRenderModule

This function registers the render module.

Syntax

int RegisterVideoRenderModule(VideoRender& renderModule);

Parameters

renderModule [in] *** Need Description added 

Return Values

The return value is 0 if the function succeeds. If the function fails, the return value is -1, and a specific error code can be retrieved by calling LastError().

Requirements

Supported platforms

Windows, Mac OS X, Linux

Header

Declared in vie_render.h

DeRegisterVideoRenderModule

This function deregisters the render module.

Syntax

int DeRegisterVideoRenderModule(VideoRender& renderModule);


Parameters

renderModule [in] *** Need Description added 

Return Values

The return value is 0 if the function succeeds. If the function fails, the return value is -1, and a specific error code can be retrieved by calling LastError().

Requirements

Supported platforms

Windows, Mac OS X, Linux

Header

Declared in vie_render.h

AddRenderer

Sets the render destination for a given render ID.

Syntax

int AddRenderer(const int renderId,

                        void* window,

                        const unsigned int zOrder,

                        const float left,

                        const float top,

                        const float right,

                        const float bottom);

Parameters

renderId [in] The render ID for the input stream. The render ID can be a channel ID, CaptureId or a fileId. Render IDs can also be retrieved for a mix or demuxed stream.

window [in] A OS specific pointer to the render destination.

zOrder [in] The render order for the stream compared to other streams rendered in the same window.

left [in] Placement of the left edge for the video stream in the window. Range: 0.0 to 1.0.

top [in] Placement of the top edge for the video stream in the window. Range: 0.0 to 1.0.

right [in] Placement of the right edge for the video stream in the window. Range: 0.0 to 1.0.

bottom [in] Placement of the bottom edge for the video stream in the window. Range: 0.0 to 1.0.

Return Values

The return value is 0 if the function succeeds. If the function fails, the return value is -1, and a specific error code can be retrieved by calling LastError().

Remarks

The function sets the render window and where in the window a video stream should be rendered.

A video channel ID, CaptureId or a fileId can be used directly as render ID. See ViEMix::GetMixRenderID() and ViEMix::GetDemuxRenderId() for how to get a render id for a mix and demuxed video stream.

The argument zOrder is used if several streams are rendered in the same window and are overlapping.

The stream is positioned in the window using left, top, right and bottom. 0,0 is top left of the window and 1,0 is bottom right.

Window is platform dependant. For Windows, window is HWND, for Mac Cocoa window is CocoaRenderView*, for Mac Carbon window is HIViewRef* and for Linux window is Window.

Requirements

Supported platforms

Windows, Mac OS X, Linux

Header

Declared in vie_render.h

RemoveRenderer

Removes the renderer for a stream

Syntax

int RemoveRenderer(const int renderId);

Parameters

renderId [in] The render ID for the input stream. The render ID can be a channel ID, CaptureId or a fileId. Render IDs can also be retrieved for a mix or demuxed stream.

Return Values

The return value is 0 if the function succeeds. If the function fails, the return value is -1, and a specific error code can be retrieved by calling LastError().

Requirements

Supported platforms

Windows, Mac OS X, Linux

Header

Declared in vie_render.h

StartRender

Starts rendering a render stream.

Syntax

int StartRender(const int renderId);

Parameters

renderId [in] The render ID for the input stream.

Return Values

The return value is 0 if the function succeeds. If the function fails, the return value is -1, and a specific error code can be retrieved by calling LastError().

Requirements

Supported platforms

Windows, Mac OS X, Linux

Header

Declared in vie_render.h

StopRender

Stops rendering a render stream.

Syntax

int StopRender(const int renderId);

Parameters

renderId [in] The render ID for the input stream.

Return Values

The return value is 0 if the function succeeds. If the function fails, the return value is -1, and a specific error code can be retrieved by calling LastError().

Requirements

Supported platforms

Windows, Mac OS X, Linux

Header

Declared in vie_render.h

ConfigureRender

Configures an already added render stream.

Syntax

int ConfigureRender(int renderId,

                             const unsigned int zOrder,

                             const float left,

                             const float top,

                             const float right,

                             const float bottom);

Parameters

renderId [in] The render ID for the input stream.

zOrder [in] The render order for the stream compared to other streams rendered in the same window.

left [in] Placement of the left edge for the video stream in the window. Range: 0.0 to 1.0.

top [in] Placement of the top edge for the video stream in the window. Range: 0.0 to 1.0.

right [in] Placement of the right edge for the video stream in the window. Range: 0.0 to 1.0.

bottom [in] Placement of the bottom edge for the video stream in the window. Range: 0.0 to 1.0.

Return Values

The return value is 0 if the function succeeds. If the function fails, the return value is -1, and a specific error code can be retrieved by calling LastError().

Remarks

The argument zOrder is used if several streams are rendered in the same window and are overlapping.

The stream is positioned in the window using left, top, right and bottom. 0,0 is top left of the window and 1,0 is bottom right.

Requirements

Supported platforms

Windows, Mac OS X, Linux

Header

Declared in vie_render.h

MirrorRenderStream

This function mirrors the rendered stream left and right or up and down.

Syntax

virtual int MirrorRenderStream(const int renderId, const bool enable,

                                            const bool mirrorXAxis,

                                            const bool mirrorYAxis);

Parameters

renderId [in] The render ID for the input stream.

enable [in] True if mirroring should be enabled, false otherwise.

mirrorXAxis [in] True if the stream should be mirrored around the x-axis, false otherwise.

mirrorYAxis [in] True if the stream should be mirrored around the y-axis, false otherwise.

Return Values

The return value is 0 if the function succeeds. If the function fails, the return value is -1, and a specific error code can be retrieved by calling LastError().

Requirements

Supported platforms

Windows, Mac OS X, Linux

Header

Declared in vie_render.h

AddRenderer

Sets the external render object. Use this function when external rendering is enabled (required).

Syntax

int AddRenderer(const int renderId,

                        RawVideoType videoInputFormat,

                        ExternalRenderer* renderer);

Parameters

renderId [in] The render ID for the input stream.

videoInputFormat [in] The color format of the frames delivered to the observer

renderer [in] external render object

Return Values

The return value is 0 if the function succeeds. If the function fails, the return value is -1, and a specific error code can be retrieved by calling LastError().

Requirements

Supported platforms

Windows, Mac OS X, Linux

Header

Declared in vie_render.h
Comments