LockFormat

Description

Blocks the execution of the image streaming thread until the image format change requested by a client application is finalized and the acquisition mode is turned on.

Syntax

int LockFormat(unsigned int channelIndex = 0);

Parameters [C/C++]

[in] unsigned int channelIndex

Index of the associated stream channel. Possible values are 0 or 1.

Return Values

S_OK

Success

E_FAIL

Failure

Example

This function runs the image generation and transfer cycle automatically synchronized with the client application:

void CGigemuDlg::videoGenerator()

{

int width;

int height;

int i=0;

char buffer[MAXWIDTH*MAXHEIGHT];

char *ptr;

while (!m_exitThread)

{

m_pCamera->LockFormat();

width=m_pCamera->GetWidth();

height=m_pCamera->GetHeight();

for (ptr=buffer; ptr < buffer+width*heigh; ptr++)

*ptr=i++;

m_pCamera->SendImage(buffer);

}

}

Remarks

Use this method to automatically synchronize your image streaming cycle with an external client application. LockFormat serves two purposes:

1) It allows you to start your image streaming cycle without waiting for the client application to issue the AcquisitionStart command. LockFormat will block the execution of the thread until the AcquisitionStart command is received from the client.

2) It lets you generate your images based on the image size and format returned by GetWidth, GetHeight and GetPixelFormat without being concerned about those parameters being modified by the client application in the middle of the image transfer. If a format change request is received from the client, LockFormat will block the execution of the thread until the virtual camera finalizes the format change procedure.

Using this method requires you to run the image streaming cycle in a separate thread in order to prevent a lock up of the application. Alternatively you can use the Write Callback to intercept AcquisitionStart and AcquisitionStop commands from the client application and synchronize them with the beginning and end of the image transfer cycle without calling LockFormat.

Note the channelIndex parameter should be used only if your virtual camera must support multiple streaming channels. For a regular GigE Vision transfer this parameter should remain in its default zero value.