Grabber::prepareLive Method

Tries to setup the image stream by connecting the device with the display and the sink and inserting frame filters and overlays.

Syntax:

bool prepareLive( bool bUseVideoRenderer );

Parameter		Description


bUseVideoRenderer		Specifies whether you want to use live display when you start the image stream.

Return value:

true, if the operation was successful. If an error occurred, call getLastError to obtain extended error information.

Remarks:

This method can be used to check, whether it is possible to insert all specified objects (frame filters, overlays and the sink) in the image stream. In the prepared state, the video capture device does not allocate bandwidth but the image stream is setup completely. Therefore, a subsequent call to startLive will take far less time than the same operation called when the image stream is stopped. This allows you to setup several image streams for several devices (using one Grabber object for every image stream) and switch between them very quickly by changing the state from prepared to live and back to prepared by calling suspendLive.

No operation which may change the layout of the video stream is permitted after prepareLive is called. These operations are:

A call to the methods stopLive and closeDev ends the prepared state.

Information:

Introduced in version 3.0

Sample:

The following example shows how to use prepareLive and suspendLive in order to grab images "simultaneously" from two high-resolution cameras that are connected to the same bus:

// Assume we connected 2 high resolution cameras to the same FireWire bus and
// set both cameras to UYVY 1024x768, 15fps.
// They will not be able to run at the same time with the specified video format
// and frame rate because each camera allocates 77% of the available bandwidth.
// Open camera 1
Grabber grabber1;
grabber1.openDev( "DFx 31AF03" );
grabber1.setVideoFormat( "UYVY (1024x768)" );
grabber1.setFPS( 15.0 );
// Open camera 2
Grabber grabber2;
grabber2.openDev( "DFx 31BF03" );
grabber2.setVideoFormat( "UYVY (1024x768)" );
grabber2.setFPS( 15.0 );
// Set sink types:
// tFrameSnapSinkPtr containing a 10 pre allocated buffers of RGB24 images.
tFrameSnapSinkPtr pSink1 = FrameSnapSink::create( FrameTypeInfo( eRGB24 ), 10 );
grabber1.setSinkType( pSink1 );
tFrameSnapSinkPtr pSink2 = FrameSnapSink::create( FrameTypeInfo( eRGB24 ), 10 );
grabber2.setSinkType( pSink2 );
// Set the grabbers to 'prepared' state.
// Almost all necessary initializations are done then,
// and startLive() will be a fast operation.
if( !grabber1.prepareLive( false ) )
{
    std::cerr << "grabber1.prepareLive failed: " << grabber1.getLastError().toString() << std::endl;
    return;
}
if( !grabber2.prepareLive( false ) )
{
    std::cerr << "grabber2.prepareLive failed: " << grabber2.getLastError().toString() << std::endl;
    return;
}
DWORD start = ::GetTickCount();
std::vector<tFrameQueueBufferPtr> buffers_cam1;
std::vector<tFrameQueueBufferPtr> buffers_cam2;
for( int i = 0; i < 10; ++i )
{
    // Snap one image from camera 1
    grabber1.startLive( false );
    auto img1 = pSink1->snapSingle();
    buffers_cam1.push_back( img1 );
    grabber1.suspendLive();
    // Snap one image from camera 2
    grabber2.startLive( false );
    auto img2 = pSink2->snapSingle();
    buffers_cam2.push_back( img2 );
    grabber2.suspendLive();
}
DWORD stop = ::GetTickCount();
std::cout << "2x10 images snapped in " << (stop-start) << "ms" << std::endl;
// Stop both cameras
grabber1.stopLive();
grabber2.stopLive();
// Save the snapped images
for( size_t i = 0; i < buffers_cam2.size(); ++i )
{
    std::string filename1 = std::string( "cam1-" ) + std::to_string( i ) + ".bmp";
    saveToFileBMP( *buffers_cam1[i], filename1 );
    std::string filename2 = std::string( "cam2-" ) + std::to_string( i ) + ".bmp";
    saveToFileBMP( *buffers_cam2[i], filename2 );
}

For another example showing the use of prepareLive, please refer to Grabber::getVideoDataDimension.

<< Grabber