video3d_stream_get_frame :: Quanser C Functions

navigation bar

video3d_stream_get_frame

Get the latest frame for the given stream.

Description

The video3d_stream_get_frame function gets the latest frame for the given stream. If no frame is available then it returns -QERR_WOULD_BLOCK. Only one frame may be retrieved at a time and the frame must be released before getting a new frame.

The handle to the frame returned by this function may be used by the video3d frame functions to get the image or motion data associated with the frame as well as ancillary metadata such as the frame number and timestamp. The frame must be released back to the video subsystem by calling video3d_frame_release when the frame is no longer needed.

Prototype

t_error
video3d_stream_get_frame(t_video3d_stream stream, t_video3d_frame * frame);

Parameters

t_video3d_stream stream

The handle to the video stream returned by video3d_stream_open.

t_video3d_frame * frame

The address of a t_video3d_frame variable to receive a handle to the image frame.

Return value

The return value is 0 if the frame was retrieved successfully. Otherwise a negative error code is returned. A value of -QERR_WOULD_BLOCK simply means that no frame was available yet at the time the function was called. Error codes are defined in quanser_errors.h. A suitable error message may be retrieved using msg_get_error_message.

Error codes

QERR_INVALID_ARGUMENT

One of the arguments is invalid.

QERR_OUT_OF_MEMORY

There is not enough memory to complete the operation.

Requirements

Include Files	Libraries
quanser_video3d.h	quanser_media.lib;quanser_communications.lib;quanser_runtime.lib;quanser_common.lib

Examples

result = video3d_start_streaming(capture);

while (result >= 0 || result == -QERR_WOULD_BLOCK)
{
    t_video3d_frame frame;

    /* Wait until the next frame period */
    timeout_add(&timeout, &timeout, &interval);
    qtimer_sleep(&timeout);

    /* Read an RGB frame */
    result = video3d_stream_get_frame(rgb_stream, &frame);
    if (result >= 0) {
        /* Get an RGB frame. If a frame is available then display it */
        result = video3d_frame_get_data(frame, image);
        if (result >= 0) {
            ... process image ...
        }

        video3d_frame_release(frame);
    }
}
    
video3d_stop_streaming(capture);