This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

`disp_vidfuncs_t`

Table of video overlay functions

Synopsis:

#include <vid.h>

typedef struct disp_vidfuncs {
    int  (*init) (...);
    void (*fini) (...);
    void (*module_info) (...);
    int  (*get_channel_caps) (...);
    int  (*set_channel_props) (...);
    int  (*next_frame) (...);
    int  (*close_channel) (...);
} disp_vidfuncs_t;

The disp_vidfuncs_t structure is a table that your driver uses to define the video overlay functions that it provides to the graphics framework. Your driver's devg_get_vidfuncs() entry point must fill in this structure.

init()

The graphics framework calls this function to initialize the modeswitcher. The prototype is:

int (*init) (disp_adapter_t *adapter,
             char *optstring)

This function should return the number of scalers available (functions similarly to the way the modeswitcher's init() function returns the number of display controllers available).

fini()

The graphics framework calls this function to free resources and disable all scalers (making them invisible). The prototype is:

void (*fini) (disp_adapter_t *adapter)

This function must free any offscreen memory that was allocated for frame data.

module_info()

The graphics framework calls this function to get information about the module. The prototype is:

void (*module_info) (disp_adapter_t *adapter,
                     disp_module_info_t *info)

This function must fill the given disp_module_info_t structure.

get_channel_caps()

The graphics framework calls this function to get the scaler capabilities for a given pixel format. The prototype is:

int (*get_channel_caps) (
        disp_adapter_t *adapter,
        int channel,
        int fmt_index,
        disp_vid_channel_caps_t *caps)

This function should fill in the disp_vid_channel_caps_t structure pointed to by caps.

The overlay scaler module is responsible for controlling scaler hardware, which is typically used for motion video (e.g. MPEG) acceleration. A hardware device may integrate zero or more scalers. Each scaler provides a "channel" for a video output stream.

The driver framework starts with a fmt_index of 0, and keeps calling get_channel_caps(), increasing fmt_index until this function returns -1. Thus, the framework can retrieve information on each format supported by the scaler denoted by channel. Channels are 0-based, i.e. if init() indicates that there are 3 channels, the valid channel numbers are 0, 1, and 2.

set_channel_props()

The graphics framework calls this function to set the scaler capabilities. The prototype is:

int (*set_channel_props) (
        disp_adapter_t *adapter,
        int channel,
        disp_vid_channel_props_t *props,
        disp_surface_t **yplane1,
        disp_surface_t **yplane2,
        disp_surface_t **uplane1,
        disp_surface_t **uplane2,
        disp_surface_t **vplane1,
        disp_surface_t **vplane2)

This function should configure the scaler channel channel, according to the contents of the disp_vid_channel_props_t structure pointed to by props. Typically, the driver allocates video memory surfaces to store the video frame data when this routine is called.

Each of the *plane* parameters it the address of a pointer to a disp_surface_t structure that describes a surface. Depending on the properties requested by props, the driver is required to return one or more surface pointers via the *plane* pointers. Unless the DISP_VID_FLAG_DOUBLE_BUFFER flag is set, your driver should ignore the *plane2 arguments. Unless the frame data format is planar (more than one surface needed), your driver should ignore the uplane* and vplane* arguments.

This function returns -1 on failure. Otherwise, it must return 1 if any of the attributes of the surfaces associated with the channel (e.g. the size or location of the surface memory) has been modified. If the state of the channel's surfaces hasn't been modified, set_channel_props() returns 0. Thus higher-level software can determine whether or not it's necessary to remap any of the frame data buffers.

(Note that the scaler may also support RGB or other non-YUV formats, in which case yplane* points to the data).

next_frame()

The graphics framework calls this function every time the higher-level software has finished preparing a new frame for display. The prototype is:

int (*next_frame)(disp_adapter_t *adapter,
                   int channel)

When double buffering, the driver typically moves the scaler's frame base pointer, so that the scaler displays the new video frame during the next display refresh cycle.

This function should return the frame index (0 or 1) if double buffering, to specify whether the data for the next frame should be copied to the *plane1 surface set, or the *plane2 surface set that was returned by set_channel_props(). In all other cases, this function should return 0.

close_channel()

The graphics framework calls this function to close a channel. The prototype is:

int (*close_channel) (disp_adapter_t *adapter,
                      int channel)

Disable the scaler specified by channel. You should free up any offscreen memory that you may have allocated for the frame data on this channel.

Classification:

Photon