Acquisition Functions

Functions
BOOL	dvcResetExpose (HANDLE hDevice)
BOOL	dvcSetCallback (HANDLE hDevice, dvcCallbackProcPtr fCallbackProcPtr, void *inUserData)
BOOL	dvcSetExposeCompleteEvent (HANDLE hDevice, HANDLE hEvent)
BOOL	dvcSetReadCompleteEvent (HANDLE hDevice, HANDLE hEvent)
BOOL	dvcSnapShot (HANDLE hDevice, double dExpose, Int32 eTrigger)
BOOL	dvcStartSequence (HANDLE hDevice, UInt32 frames)
BOOL	dvcStartSequenceEx (HANDLE hDevice, UInt32 frames, Int32 eTrigger)
BOOL	dvcStopSequence (HANDLE hDevice)
BOOL	dvcTakePicture (HANDLE hDevice)

---

Function Documentation

BOOL dvcResetExpose

(

HANDLE

hDevice

)

Parameters:

hDevice

returned from dvcOpenCamera().

See also:

dvcSnapShot(), dvcStartSequence(), dvcSetExtReset().

Asynchronous reset of the start of an exposure. If the camera is in the process of exposing, the current exposure is aborted, the charge flushed and a new exposure is initiated. The camera is automatically triggered when a snapshot or sequence is started with dvcSnapShot() or dvcStartSequence() and the trigger mode is dvcTriggerTimed.

Examples:

testEvent.cpp.

BOOL dvcSetCallback	(	HANDLE	hDevice,
		dvcCallbackProcPtr	fCallbackProcPtr,
		void *	inUserData
	)

Set an application function to be called after each image is transferred. Enables multithreaded service for image captures.

Parameters:

	hDevice	camera handle returned from dvcOpenCamera().
	fCallbackProcPtr	is the address of a function called after an image is transferred to the host memory.
	inUserData	is a pointer to an application context returned as an element in the pCallBackProcPtr argument.

The API's interrupt service thread is suspended during the callback function. If another image arrives before the completion of this function, the data for that frame is queued and another call to this function occurs immediately. However, the queue can only hold three frames. If the callback continues to delay for periods longer than the time for a new frame to arrive, eventually data will be lost. Dropped frames can be monitored by checking the ulFrame element in the callback argument.

The argument to the callback function is a pointer to a dvcCallbackData structure defined as;

  typedef struct _dvcCallback_t {
    HANDLE         hDevice ;      // Handle to camera
    USHORT        *pImageBuffer ; // Pointer to raw image data
    UInt32         ulWidth ;      // width of image data
    UInt32         ulHeight ;     // height of image data
    UInt32         ulFrame ;      // frame count
    double         dTimeStamp ;   // time image was captured
    void          *pUserData ;    // application data
    ImageMetaData sMeta ;         // meta with associated image buffer
  } dvcCallbackData, *dvcCallbackDataP ;

Example:

  void
  myFrameService( void *pVData )
  {
      dvcCallbackDataP pCbData = (dvcCallbackDataP)pVData ;
      dvcPrintf(0,"Image number %d w %d x h %d  pix(0,0) %d\n",
          pCbData->ulFrame,
          pCbData->ulWidth,
          pCbData->ulHeight,
          *pCbData->pImageBuffer);
  }

  void 
  myStartTransfers( HANDLE hDevice, void *myData )
  {
      Int32 frame ;
      dvcStopSequence(hDevice) ;    // Stop any existing captures..
      dvcSetCallback(hDevice, (dvcCallbackProcP) myFrameService, myData);
      frame = dvcGetFrameCount(hDevice);
      dvcStartSequence(hDevice, 0) ;
      while( dvcGetFrameCount(hDevice) < frame + 10 ) ;
      dvcStopSequence(hDevice);
  }

BOOL dvcSetExposeCompleteEvent	(	HANDLE	hDevice,
		HANDLE	hEvent
	)

installs an event handle signaled after an exposure completes.

Parameters:

	hDevice	handle returned from dvcOpenCamera().
	hEvent	handle created with the Windows API CreateEvent().

See also:

dvcSetReadCompleteEvent(), dvcGetExposeCompleteEvent().

During acquisitions, after an exposure is triggered, the camera's sensor integrates for a variable period of time depending on the exposure timing. When the exposure completes, the sensor transfers the charge to a masked area on the chip and starts the column and row clocks on the sensor to transfer the charge from the masked pixels to the analog to digital converter. When the first pixel data arrives in the host's RAM, the API calls the Windows event function,

     SetEvent(hEvent)

to signal the application the exposure phase has completed and readout is in progress. If a single image is being captured, this event allows the application to modify the light path without effecting the captured data. During streaming operations with overlapped exposure and readout, if the exposure time is less than the time required to readout the previous frame, the sensor's charge is cleared at the time interval of the readout time minus the exposure time, and the next exposure starts. During streaming operations with overlapped exposure and readout, if the exposure time is equal or greater than the time required to readout the previous frame, the next exposure starts immediately.

Examples:

RamCapture.cpp, and testEvent.cpp.

BOOL dvcSetReadCompleteEvent	(	HANDLE	hDevice,
		HANDLE	hEvent
	)

installs an event handle signaled after an image transfer completes.

Parameters:

	hDevice	handle returned from dvcOpenCamera().
	hEvent	handle created with the Windows API CreateEvent().

See also:

dvcSetExposeCompleteEvent(), dvcGetReadCompleteEvent().

During acquisitions, after the last pixel is transferred from the camera to the host's RAM, the API calls the Windows event function,

     SetEvent(hEvent)

to signal the application the transfer has completed.

Examples:

avgdvc.cpp, FullScreen.cpp, RamCapture.cpp, and testEvent.cpp.

BOOL dvcSnapShot	(	HANDLE	hDevice,
		double	dExpose,
		Int32	eTrigger
	)

Capture a single frame with a given exposure.

Parameters:

	hDevice	camera handle returned from dvcOpenCamera().
	dExpose	time in milliseconds to expose the CCD.
	eTrigger	controls the trigger type (

See also:

dvcStartSequenceEx() ).

dvcStartSequenceEx().

Examples:

testEvent.cpp.

BOOL dvcStartSequence	(	HANDLE	hDevice,
		UInt32	frames
	)

Start captures with using the camera's internal timing for exposure.

Parameters:

	hDevice	camera handle returned from dvcOpenCamera().
	frames	the number of frames to capture or 0 to capture indefinitely.

See also:

dvcStartSequenceEx().

Examples:

avgdvc.cpp, FullScreen.cpp, MultiCamera.cpp, RamCapture.cpp, snapdvc.cpp, and testEvent.cpp.

BOOL dvcStartSequenceEx	(	HANDLE	hDevice,
		UInt32	frames,
		Int32	eTrigger
	)

Start captures and return immediately. To determine when an exposure has completed, use dvcWaitExpose(), and to determine when data has been transferred to the host, use dvcWaitImage(). Data transfers from the camera to the API occur always to buffers allocated and managed internally by the API. To transfer raw image data to an application buffer, use the functions dvcReadImage() or dvcReadImageEx().

Parameters:

	hDevice	camera handle returned from dvcOpenCamera().
	frames	the number of frames to capture or 0 to capture indefinitely.
	eTrigger	optionally enables external triggering of the start or exposure.

Values for eTrigger are ;

 typedef enum {
        dvcTriggerTimed = 0, // internal camera timing controls exposure
        dvcTriggerBulb,      // external TTL controls exposure
        dvcTriggerStrobe     // external TTL starts,  camera controls exposure
 } dvcTriggerModes

Example:

 BOOL
 dvcGrab( HANDLE hDevice, double dMilliSeconds, USHORT *myBuffer, Int32 width, Int32 height )
 {
     BOOL bOK = FALSE ;
     double dTimeout =
         dvcGetExposeMsec(hDevice)       // Expose time
         + dvcTimeToReadImage(hDevice)   // Time to transfer
         + 100.0 ;  // Allow for 100 millisecond overhead..
     if(!dvcStartSequenceEx(hDevice,1,dvcTriggerTimed))
     {
        dvcPrintf(0,"Start Error!\n");
        return FALSE ;
     }
     if(!dvcWaitImage(hDevice), dTimeout ))
     {
        // Handle time out..
        dvcPrintf(0,"Timeout!\n");
        bOK = FALSE ;
     }
     else if(!dvcReadImage(hDevice,myBuffer,0,0,width,height))
     {
        // Handle read error
        dvcPrintf(0,"Read Error!\n");
        bOK = FALSE ;
     }
     else bOK = TRUE ;
     // Stop and release any resources.
     dvcStopSequence(hDevice);
     return bOK ;
 }

See also:

dvcSnapShot(), dvcSetExposeMsec(), dvcSetCallback(), dvcWaitExpose(), dvcWaitImage().

BOOL dvcStopSequence

(

HANDLE

hDevice

)

Stop a capture sequence and releases any system resources.

Parameters:

hDevice

camera handle returned from dvcOpenCamera().

Returns:

TRUE if acquisitions were stopped.

Examples:

avgdvc.cpp, FullScreen.cpp, MultiCamera.cpp, snapdvc.cpp, and testEvent.cpp.

BOOL dvcTakePicture

(

HANDLE

hDevice

)

Capture a single image and wait for completion.

Parameters:

hDevice

camera handle returned from dvcOpenCamera().

See also:

dvcSnapShot(), dvcWaitImage().

---