Starting and Stopping Image Acquisition

Once openDevice() returns successfully, the engine calls your adaptor's startCapture() function to start acquiring data.

The engine calls your adaptor's stopCapture() function when a user calls the stop or closepreview function on a video input object, or when the specified number of frames has been acquired and the acquisition is complete. For example,

vid = videoinput('winvideo',1);
set(vid,'FramesPerTrigger',1000); // 
start(vid);
stop(vid);

Suggested Algorithm for startCapture()

The startCapture() function typically performs the following tasks.

Check whether an acquisition is already occurring, using the IAdaptor member function isAcquiring(). If it is, exit.
Send a message to the acquisition thread, using the Windows^® PostThreadMessage() function, telling it to begin acquiring image frames from the device. See Sending a Message to the Acquisition Thread for more information.
Note
Sending a start message to the acquisition thread is only required if your adaptor uses a thread-based design. Adaptors can also use asynchronous interrupts (callbacks) to acquire frames, if the device supports this. Refer to the documentation that came with your device's SDK for more information.

The startCapture() function also typically makes sure that the latest image acquisition object properties are used (see Implementing Get and Set Support for Device-Specific Properties), and configures hardware triggers, if supported and set (see Supporting Hardware Triggers).

Sending a Message to the Acquisition Thread

To send a message to a thread, use the Windows PostThreadMessage() function. The adaptor's acquisition thread function uses the Windows GetMessage() function to receive these messages — see Example: Opening a Connection.

The PostThreadMessage() function accepts these parameters:

BOOL PostThreadMessage( DWORD idThread,
                        UINT Msg,
                        WPARAM wParam,
                        LPARAM lParam
);

The following table describes how to set these parameters for an adaptor. For more information about sending thread messages, see Microsoft documentation.

Parameter	Description
`idThread`	Identifier of the thread to which the message is to be posted, returned by `CreateThread()`.
`Msg`	Message to be posted. Microsoft^® defines a range of values for user messages, beginning with the value `WM_USER`.
`wParam`	Additional message-specific information
`lParam`	Additional message-specific information

Example: Initiating Acquisition

This example illustrates a simple startCapture() function. This function takes no arguments and returns a Boolean value indicating whether the video input object is in start state.

Replace the stub implementation in the MyDeviceAdaptor.cpp file with this code and then rebuild your adaptor.

bool MyDeviceAdaptor::startCapture(){
    // Check if device is already acquiring frames. 
    if (isAcquiring())
        return false; 

    // Send start message to acquisition thread 
    PostThreadMessage(_acquireThreadID, WM_USER, 0, 0);
    
    return true;
}

Start the MATLAB^® software and run your adaptor to verify that your acquisition thread gets the start message from startCapture().

Suggested Algorithm for stopCapture()

The stopcapture() function typically performs these tasks.

Checks whether the adaptor is already stopped by calling the isAcquiring() function. If the device is not currently acquiring data, return true.
Stops the frame acquisition loop and stops the device, if necessary
Note
It is important not to exit the stopCapture() function while the acquisition thread function is still acquiring frames. One way to do this is to try to acquire a critical section. When you are able to acquire the critical section, you can be sure that the frame acquisition loop has ended, giving up its critical section.

Example

The following example illustrates a simple stopCapture() function. This function takes no arguments and returns a Boolean value indicating whether the video input object is in stopped state. Replace the stub implementation in the MyDeviceAdaptor.cpp file with this code and then rebuild your adaptor.

bool MyDeviceAdaptor::stopCapture(){

// If the device is not acquiring data, return. 
   if (!isOpen()) 
      return true;

//**********************************************************
// Insert calls to your device's SDK to stop the device, if
// necessary.
//**********************************************************

   return true;
}

The stopCapture() function in the demo adaptor provides another example of how to stop the frame acquisition loop. The adaptor defines a flag variable that it checks each time it enters the frame acquisition loop. To break out of the frame acquisition loop, the demo adaptor sets this flag variable to false. See the demo adaptor source code for more details.