Data Transfers


Functions

BOOL dvcAllocateUserBuffers (HANDLE hDevice, dvcBufStructP pBufStruct, Int32 nBuffers)
BOOL dvcCopyCharImageData (HANDLE hDevice, PBYTE pBuffer, PBYTE pLut)
BOOL dvcCopyShortImageData (HANDLE hDevice, PUSHORT pBuffer)
BOOL dvcGetDriverBuffers (HANDLE hDevice, PInt32 pNBuffers, PInt32 pLastBuffer)
BOOL dvcGetExposeCompleteEvent (HANDLE hDevice, PHANDLE phEvent)
Int32 dvcGetExposeCount (HANDLE hDevice)
UInt32 dvcGetFrameCount (HANDLE hDevice)
double dvcGetFrameRate (HANDLE hDevice)
UInt32 dvcGetImageBytes (HANDLE hDevice)
BOOL dvcGetImageFormat (HANDLE hDevice, Int32 nX, Int32 nY, PInt32 pFormat)
Int32 dvcGetImageHeight (HANDLE hDevice)
Int32 dvcGetImageWidth (HANDLE hDevice)
BOOL dvcGetReadCompleteEvent (HANDLE hDevice, PHANDLE phEvent)
BOOL dvcGetStreamBytes (HANDLE hDevice, PInt32 pState, PULONG pnBytes)
Int32 dvcGetStreamCount (HANDLE hDevice)
double dvcGetStreamTime (HANDLE hDevice)
double dvcGetTimeToExposeComplete (HANDLE hDevice)
double dvcGetTimeToNextExpose (HANDLE hDevice)
double dvcGetTimeToReadComplete (HANDLE hDevice)
double dvcGetTimeToReadImage (HANDLE hDevice)
BOOL dvcGetUserBufferId (HANDLE hDevice, PInt32 pID)
BOOL dvcHasCallback (HANDLE hDevice)
BOOL dvcReadDriverBuffer (HANDLE hDevice, Int32 nBuffer, PUSHORT pBuffer, ULONG uLeft, ULONG uTop, ULONG uWidth, ULONG uHeight)
BOOL dvcReadDriverBufferEx (HANDLE hDevice, Int32 nBuffer, PUSHORT pBuffer, ULONG uLeft, ULONG uTop, ULONG uWidth, ULONG uHeight, ImageMetaDataP pMeta)
BOOL dvcReadImage (HANDLE hDevice, USHORT *pBuffer, UInt32 left, UInt32 top, UInt32 width, UInt32 height)
BOOL dvcReadImageAndMeta (HANDLE hDevice, PUSHORT pBuffer, ULONG uLeft, ULONG uTop, ULONG uWidth, ULONG uHeight, ImageMetaDataP pMeta)
BOOL dvcReadImageEx (HANDLE hDevice, USHORT *pBuffer, UInt32 left, UInt32 top, UInt32 width, UInt32 height, UInt32 lineWidth)
BOOL dvcReadImageRGB48 (HANDLE hDevice, PUSHORT pRGBBuffer, ULONG uLeft, ULONG uTop, ULONG uWidth, ULONG uHeight)
BOOL dvcReadLine (HANDLE hDevice, UInt32 x, UInt32 y, UInt32 w, USHORT *pData)
BOOL dvcReadMeta (HANDLE hDevice, ImageMetaDataP pMeta)
BOOL dvcReadPixel (HANDLE hDevice, UInt32 x, UInt32 y, PInt32 pData)
BOOL dvcReadRGB32 (HANDLE hDevice, PULONG buffer, ULONG uLeft, ULONG uTop, ULONG uWidth, ULONG uHeight, ULONG lineWidth, BOOL bWhiteBalance)
BOOL dvcReleaseUserBuffers (dvcBufStructP pBufStruct)
BOOL dvcSetUserBuffers (HANDLE hDevice, dvcBufStructP pBufStruct)
BOOL dvcWaitExpose (HANDLE hDevice, double dWaitMilliSeconds)
BOOL dvcWaitImage (HANDLE hDevice, double dWaitMilliSeconds)

Function Documentation

BOOL dvcAllocateUserBuffers ( HANDLE  hDevice,
dvcBufStructP  pBufStruct,
Int32  nBuffers 
)

Allocate application ring buffers for streaming acquisitions.

Parameters:
hDevice handle from dvcOpenCamera().
pBufStruct pointer to a dvcBufStruct structure filled on return.
nBuffers the number of buffers to allocate.
Returns:
FALSE of insufficent memory is available.
Allocates nBuffers image buffers, each the size of the camera's current readout dimensions ( as returned by dvcGetXDim() and dvcGetYDim() ). On entry, pBufStruct is reset and assumed to have had any references to buffers allocated with a previous call released. Each allocated buffer pBuffers[n] in pBufStruct has a corresponding state flag pBufferStatus and ImageMetaData structure pMeta. The application must call dvcReleaseUserBuffers() to release the allocated memory and resources from this call.

See also:
dvcSetUserBuffers(), dvcReleaseUserBuffers().

BOOL dvcCopyCharImageData ( HANDLE  hDevice,
PBYTE  pBuffer,
PBYTE  pLut 
)

Returns a captured image as an 8-bit array.

Parameters:
hDevice handle from dvcOpenCamera().
pBuffer byte array of dimensions dvcGetXDim() by dvcGetYDim().
pLut byte array used as a lookup table to convert the 10 or 12-bit raw image data to bytes.
An exception is generated if pBuffer 's size is less than the width and height of the readout area of the CCD.
See also:
dvcReadImage(), dvcGetXDim(), dvcGetYDim().

BOOL dvcCopyShortImageData ( HANDLE  hDevice,
PUSHORT  pBuffer 
)

returns a captured image as an 16-bit array.

Parameters:
hDevice handle from dvcOpenCamera().
pBuffer short array of dimensions dvcGetXDim() by dvcGetYDim().
An exception is generated if pBuffer 's size is less than the width and height of the readout area of the CCD.
See also:
dvcReadImage(), dvcGetXDim(), dvcGetYDim().

BOOL dvcGetDriverBuffers ( HANDLE  hDevice,
PInt32  pNBuffers,
PInt32  pLastBuffer 
)

Parameters:
hDevice handle from dvcOpenCamera().
pNBuffers returned with the number of buffers in the API's internal ring buffer.
pLastBuffer returned with the index of the last buffer written.
Returns:
TRUE if the internal ring buffers are allocated and at least one has been filled.

BOOL dvcGetExposeCompleteEvent ( HANDLE  hDevice,
PHANDLE  phEvent 
)

returns a previously installed expose complete event handle.

Parameters:
hDevice returned from dvcOpenCamera().
phEvent handle for a previously installed event or NULL.
See also:
dvcSetExposeCompleteEvent(), dvcSetReadCompleteEvent().

Int32 dvcGetExposeCount ( HANDLE  hDevice  ) 

Parameters:
hDevice handle returned from dvcOpenCamera().
Returns:
the number of exposures started since the last call to dvcStartSequence() or dvcStartSequenceEx().

UInt32 dvcGetFrameCount ( HANDLE  hDevice  ) 

Get the frame number of the last image transferred.

Parameters:
hDevice camera handle returned from dvcOpenCamera().
Returns:
the frame count since the start of the application.
Examples:
RamCapture.cpp, and testEvent.cpp.

double dvcGetFrameRate ( HANDLE  hDevice  ) 

Parameters:
hDevice handle from dvcOpenCamera().
Returns:
frames per second since beginning of a sequence.
See also:
dvcStartSequenceEx().
Examples:
FullScreen.cpp.

UInt32 dvcGetImageBytes ( HANDLE  hDevice  ) 

Parameters:
hDevice handle from dvcOpenCamera().
Returns:
the number of bytes needed to read an entire image of raw data.

BOOL dvcGetImageFormat ( HANDLE  hDevice,
Int32  nX,
Int32  nY,
PInt32  pFormat 
)

returns the bayer pattern.

Parameters:
hDevice returned from dvcOpenCamera().
nX column for the first pixel.
nY row for the first pixel.
pFormat returns with one of the following; 
        DVC_FORMAT_BAYER_10_RG,
        DVC_FORMAT_BAYER_10_GR,
        DVC_FORMAT_BAYER_10_BG,
        DVC_FORMAT_BAYER_10_GB,
        DVC_FORMAT_BAYER_12_RG,
        DVC_FORMAT_BAYER_12_GR,
        DVC_FORMAT_BAYER_12_BG,
        DVC_FORMAT_BAYER_12_GB,
        DVC_FORMAT_MONO_10,
        DVC_FORMAT_MONO_12,

Int32 dvcGetImageHeight ( HANDLE  hDevice  ) 

Parameters:
hDevice handle from dvcOpenCamera().
Returns:
the vertical ( binned ) height in pixels of the last image captured.
See also:
dvcGetImageWidth(), dvcGetYDim(), dvcGetCCDHeight().
Returns the height of the last captured image in the API's ring buffer. The API's ring buffers are updated in dvcStartSequence() or dvcSnapShot() after a binning or ROI change.
Examples:
FullScreen.cpp.

Int32 dvcGetImageWidth ( HANDLE  hDevice  ) 

Returns the width of the last captured image in the API's ring buffer. The API's ring buffers are updated in dvcStartSequence() or dvcSnapShot() after a binning or ROI change.

Parameters:
hDevice handle from dvcOpenCamera().
Returns:
the horizontal ( binned ) width in pixels of the last image captured.
See also:
dvcGetImageHeight(), dvcGetXDim(), dvcGetCCDWidth().
Examples:
FullScreen.cpp.

BOOL dvcGetReadCompleteEvent ( HANDLE  hDevice,
PHANDLE  phEvent 
)

returns a previously installed read complete event handle.

Parameters:
hDevice returned from dvcOpenCamera().
phEvent handle for a previously installed event or NULL.
See also:
dvcSetReadCompleteEvent(), dvcSetExposeCompleteEvent().

BOOL dvcGetStreamBytes ( HANDLE  hDevice,
PInt32  pState,
PULONG  pnBytes 
)

Parameters:
hDevice handle returned from dvcOpenCamera().
pState returns the readout status
pnBytes returns the number of bytes transferred in the next buffer.
See also:
dvcGetStreamState().

Int32 dvcGetStreamCount ( HANDLE  hDevice  ) 

Returns:
number of frames acquired since the last call to dvcStartSequenceEx().
Parameters:
hDevice camera handle returned from dvcOpenCamera().
See also:
dvcStartSequenceEx().

double dvcGetStreamTime ( HANDLE  hDevice  ) 

Parameters:
hDevice handle from dvcOpenCamera().
Returns:
time in milliseconds since beginning of a sequence.
See also:
dvcStartSequenceEx().

double dvcGetTimeToExposeComplete ( HANDLE  hDevice  ) 

Parameters:
hDevice returned from dvcOpenCamera().
Returns:
the time in milliseconds until an exposure is finished.

double dvcGetTimeToNextExpose ( HANDLE  hDevice  ) 

Parameters:
hDevice returned from dvcOpenCamera().
Returns:
the time in milliseconds until the start of the next exposure.

double dvcGetTimeToReadComplete ( HANDLE  hDevice  ) 

Parameters:
hDevice returned from dvcOpenCamera().
Returns:
the time in milliseconds until a complete frame has been transferred.

double dvcGetTimeToReadImage ( HANDLE  hDevice  ) 

Parameters:
hDevice handle from dvcOpenCamera().
Returns:
the time in milliseconds to transfer an image to host memory.
Examples:
avgdvc.cpp, FullScreen.cpp, RamCapture.cpp, and testEvent.cpp.

BOOL dvcGetUserBufferId ( HANDLE  hDevice,
PInt32  pID 
)

return the last ring buffer filled.

Parameters:
hDevice handle from dvcOpenCamera().
pID zero indexed id in the dvcBufStruct installed in the driver.
Returns:
FALSE if no ring buffer is installed or no buffers filled.
See also:
dvcSetUserBuffers(), dvcAllocateUserBuffers().
During streaming acquisitions with an application ring buffer, the last buffer written in the ring buffer array is returned in pID.

BOOL dvcHasCallback ( HANDLE  hDevice  ) 

Test if a callback is currently installed with dvcSetCallback().

Parameters:
hDevice handle from dvcOpenCamera().
Returns:
TRUE if an application callback is installed.

BOOL dvcReadDriverBuffer ( HANDLE  hDevice,
Int32  nBuffer,
PUSHORT  pBuffer,
ULONG  uLeft,
ULONG  uTop,
ULONG  uWidth,
ULONG  uHeight 
)

copy the image data from an internal API buffer.

Parameters:
hDevice returned from dvcOpenCamera().
nBuffer zero indexed driver buffer id.
pBuffer user supplied short array of uWidth by uHeight size.
uLeft the left most pixel to copy from the the driver buffer.
uTop the top most pixel to copy from the driver buffer.
uWidth the width of the area to copy. Must be less than dvcGetImageWidth().
uHeight the height of the area to copy. Must be less than dvcGetImageHeight().
Returns:
FALSE if no data is available.
See also:
dvcReadImage(), dvcGetDriverBuffers().
Copy the image data from the ring buffer indexed by nBuffer to the application supplied pBuffer.

BOOL dvcReadDriverBufferEx ( HANDLE  hDevice,
Int32  nBuffer,
PUSHORT  pBuffer,
ULONG  uLeft,
ULONG  uTop,
ULONG  uWidth,
ULONG  uHeight,
ImageMetaDataP  pMeta 
)

copy the image and meta data from an internal API buffer.

Parameters:
hDevice returned from dvcOpenCamera().
nBuffer zero indexed driver buffer id.
pBuffer user supplied short array of uWidth by uHeight size.
uLeft the left most pixel to copy from the the driver buffer.
uTop the top most pixel to copy from the driver buffer.
uWidth the width of the area to copy. Must be less than dvcGetImageWidth().
uHeight the height of the area to copy. Must be less than dvcGetImageHeight().
pMeta returned with the ImageMetaData structure filled.
Returns:
FALSE if no data is available.
See also:
dvcReadImage(), dvcGetDriverBuffers().
Copy the image and associated meta data from the ring buffer indexed by nBuffer to the application supplied pBuffer buffer and pMeta structure.

BOOL dvcReadImage ( HANDLE  hDevice,
USHORT *  pBuffer,
UInt32  left,
UInt32  top,
UInt32  width,
UInt32  height 
)

Copy raw data from the last frame to an application buffer.

Parameters:
hDevice camera handle returned from dvcOpenCamera().
pBuffer previously allocated buffer of width x height x 2 bytes.
left is the first binned column to copy to the buffer.
top is the first binned row to copy to the buffer.
width is the number of binned pixels per row to copy.
height is the number of binned pixels per column to copy.
Examples:
MultiCamera.cpp, RamCapture.cpp, snapdvc.cpp, and testEvent.cpp.

BOOL dvcReadImageAndMeta ( HANDLE  hDevice,
PUSHORT  pBuffer,
ULONG  uLeft,
ULONG  uTop,
ULONG  uWidth,
ULONG  uHeight,
ImageMetaDataP  pMeta 
)

Copy raw data from the last frame to an application buffer.

Parameters:
hDevice camera handle returned from dvcOpenCamera().
pBuffer application supplied buffer of uWidth x uHeight x 2 bytes.
uLeft is the first binned column to copy to the buffer.
uTop is the first binned row to copy to the buffer.
uWidth is the number of binned pixels per row to copy.
uHeight is the number of binned pixels per column to copy.
pMeta is a ImageMetaData struct returned with the associated data.
See also:
dvcReadImage(), dvcReadMeta().

BOOL dvcReadImageEx ( HANDLE  hDevice,
USHORT *  pBuffer,
UInt32  left,
UInt32  top,
UInt32  width,
UInt32  height,
UInt32  lineWidth 
)

Copy raw data from the last frame to an application buffer.

Parameters:
hDevice camera handle returned from dvcOpenCamera().
pBuffer previously allocated buffer of lineWidth x height x 2 bytes.
left is the first binned column to copy to the buffer.
top is the first binned row to copy to the buffer.
width is the number of binned pixels per row to copy.
height is the number of binned pixels per column to copy.
lineWidth is the width of pBuffer in pixels ( 2 bytes/pixel ).
See also:
dvcReadImage().

BOOL dvcReadImageRGB48 ( HANDLE  hDevice,
PUSHORT  pRGBBuffer,
ULONG  uLeft,
ULONG  uTop,
ULONG  uWidth,
ULONG  uHeight 
)

Parameters:
hDevice camera handle returned from dvcOpenCamera().
pRGBBuffer application supplied buffer of uWidth x uHeight x 2 bytes x 3 channels
uLeft is the first binned column to copy to the buffer.
uTop is the first binned row to copy to the buffer.
uWidth is the number of binned pixels per row to copy.
uHeight is the number of binned pixels per column to copy.
See also:
dvcReadImage(), dvcReadRGB32().
Examples:
MultiCamera.cpp, and snapdvc.cpp.

BOOL dvcReadLine ( HANDLE  hDevice,
UInt32  x,
UInt32  y,
UInt32  w,
USHORT *  pData 
)

Copy a line data from the last frame to an application buffer.

Parameters:
hDevice camera handle returned from dvcOpenCamera().
pData previously allocated buffer of
  • w x 2 bytes.
x is the first binned column to copy to the buffer.
y is the first binned row to copy to the buffer.
w is the number of binned pixels to copy.
See also:
dvcReadImage(), dvcReadImageEx().

BOOL dvcReadMeta ( HANDLE  hDevice,
ImageMetaDataP  pMeta 
)

copies the meta data from the last image transferred.

Parameters:
hDevice camera handle returned from dvcOpenCamera().
pMeta is a ImageMetaData struct returned with the associated data.

BOOL dvcReadPixel ( HANDLE  hDevice,
UInt32  x,
UInt32  y,
PInt32  pData 
)

Copy a data from a single pixel in the last frame to an application buffer.

Parameters:
hDevice camera handle returned from dvcOpenCamera().
pData pointer to a 32 bit Int32 returning the value of the pixel at x,y.
x is the binned column.
y is the binned row.
See also:
dvcReadImage(), dvcReadImageEx().

BOOL dvcReadRGB32 ( HANDLE  hDevice,
PULONG  buffer,
ULONG  uLeft,
ULONG  uTop,
ULONG  uWidth,
ULONG  uHeight,
ULONG  lineWidth,
BOOL  bWhiteBalance 
)

copy an image to a RGB buffer.

Parameters:
hDevice camera handle returned from dvcOpenCamera().
buffer application supplied buffer of lineWidth x uHeight x 4 bytes
uLeft is the first binned column to copy to the buffer.
uTop is the first binned row to copy to the buffer.
uWidth is the number of binned pixels per row to copy.
uHeight is the number of binned pixels per column to copy.
lineWidth is the number bytes per line in buffer.
bWhiteBalance if TRUE white balances the returned image buffer.
See also:
dvcReadImage().

BOOL dvcReleaseUserBuffers ( dvcBufStructP  pBufStruct  ) 

release an application ring buffer and memory.

Parameters:
pBufStruct dvcBufStruct allocated with dvcAllocateUserBuffers().
Returns:
TRUE if pBufStruct resources were released.
See also:
dvcAllocateUserBuffers(), dvcSetUserBuffers().

BOOL dvcSetUserBuffers ( HANDLE  hDevice,
dvcBufStructP  pBufStruct 
)

install an application ring buffer.

Parameters:
hDevice handle returned from dvcOpenCamera().
pBufStruct dvcBufStruct pointer to a ring buffer from dvcAllocateUserBuffers() or NULL to remove a previously installed ring buffer.
Installs an application ring buffer created with dvcAllocateUserBuffers() in the camera driver. Any changes to a camera's readout dimensions ( dvcSetBinning(), dvcSetHVBin(), dvcSetROI() ) must be called before allocating the buffers. After installing a ring buffer, starting a sequence capture with dvcStartSequence() or dvcStartSequenceEx() fills the ring buffers with image data automatically. After each buffer is filled, the read complete event ( dvcSetReadCompleteEvent() ) is signaled and a call to dvcGetUserBufferId() returns the index of the last buffer written. 
BOOL 
grabRingBuffer(HANDLE hDevice, int nBuffers, in nCycles )
{
    dvcBufStruct bufS ;
    int i ;

    if(nCycles < 1) nCycles = 1 ;

    if(!dvcAllocateUserBuffers(hDevice, &bufS, nBuffers))
    {
        fprintf(stderr,"Error allocating user buffers!\n");
        return FALSE ;
    }

    BOOL bRC = TRUE ;
    HANDLE hExpose, hRead ;

    hExpose = CreateEvent(NULL,FALSE,FALSE,NULL) ;
    hRead = CreateEvent(NULL,FALSE,FALSE,NULL);

    bRC = dvcSetExposeCompleteEvent(hDevice, hExpose);
    if(!bRC) {
        fprintf(stderr,"Error setting ExposeComplete!\n");
        dvcReleaseUserBuffers(&bufS);
        CloseHandle(hExpose);
        CloseHandle(hRead);
        return FALSE ; 
    }
    bRC = dvcSetReadCompleteEvent(hDevice, hRead);
    if(!bRC) {
        fprintf(stderr,"Error setting ReadComplete!\n");
        dvcReleaseUserBuffers(&bufS);
        dvcSetExposeCompleteEvent(hDevice, NULL);
        dvcSetReadCompleteEvent(hDevice, NULL);
        CloseHandle(hExpose);
        CloseHandle(hRead);
        return FALSE ; 
    }

    bRC = dvcSetUserBuffers(hDevice, &bufS);
    if(!bRC) {
        fprintf(stderr,"Error setting UserBuffers!\n");
        dvcReleaseUserBuffers(&bufS);
        dvcSetExposeCompleteEvent(hDevice, NULL);
        dvcSetReadCompleteEvent(hDevice, NULL);
        CloseHandle(hExpose);
        CloseHandle(hRead);
        return FALSE ; 
    }

    bRC = dvcStartSequenceEx(hDevice, 0, 0) ;
    if(!bRC) fprintf(stderr,"Error starting sequence!\n");

    int nRingBuffer ;
    for(i=0;bRC && i<nBuffers*nCycles;i++) 
    {
        if(WaitForSingleObject(hExpose,1000) != WAIT_OBJECT_0 ) {
            fprintf(stderr,"Error waiting expose!\n");
            bRC = FALSE ;
        }

        if(WaitForSingleObject(hRead, 1000) != WAIT_OBJECT_0 ) {
            fprintf(stderr,"Error waiting read!\n");
            bRC = FALSE ;
        }

        if(!dvcGetUserBufferId(hDevice, &nRingBuffer)) {
            fprintf(stderr,"Error getting buffer id!\n");
            bRC = FALSE ;
        }

        if(bRC) 
        {
            fprintf(stderr,
            "Buffer %d meta Stream %d time %.2f status %d ring %d cyles %d\n",
                nRingBuffer,
                bufS.pMeta[nRingBuffer].ulStreamCount,
                dvcElapseTime(bufS.pMeta[nRingBuffer].dFrameTime),
                bufS.pBufferStatus[nRingBuffer],
                bufS.pMeta[nRingBuffer].ulRingBuffer,
                bufS.pMeta[nRingBuffer].ulBufferWriteCount) ;

            // If we're cycling, clear the buffer's status
            // to enable refilling..
            if(nCycles > 1)
                bufS.pBufferStatus[nRingBuffer] = 0 ;

        }

    }

    dvcStopSequence(hDevice);
    dvcSetUserBuffers(hDevice, NULL);

    dvcReleaseUserBuffers(&bufS);
    dvcSetExposeCompleteEvent(hDevice, NULL);
    dvcSetReadCompleteEvent(hDevice, NULL);
    CloseHandle(hExpose);
    CloseHandle(hRead);

    return bRC ;

}

BOOL dvcWaitExpose ( HANDLE  hDevice,
double  dWaitMilliSeconds 
)

Wait for an exposure to complete and data transfers to start.

Parameters:
hDevice camera handle returned from dvcOpenCamera().
dWaitMilliSeconds is the time in milliseconds to wait before returning. Delays are implemented using pthread conditional variables to minimize CPU overhead while waiting.
Returns:
TRUE when an exposure is complete.
See also:
dvcStartSequenceEx(), dvcSnapShot().

BOOL dvcWaitImage ( HANDLE  hDevice,
double  dWaitMilliSeconds 
)

Wait for an image transfer to complete.

Parameters:
hDevice camera handle returned from dvcOpenCamera().
dWaitMilliSeconds is the time in milliseconds to wait before returning.
Returns:
TRUE when an image has been transferred to host memory.
See also:
dvcStartSequenceEx(), dvcSnapShot().
Examples:
MultiCamera.cpp, and snapdvc.cpp.

©DVC Company, 2006. All rights reserved.    www.dvcco.com   Created Thu Nov 16 10:07:22 2006