Functions
int	pdv_read (PdvDev pdv_p, unsigned char *buf, unsigned long size)
	Reads image data from the EDT framegrabber board. pdv_read is not supported on all platforms and is included mainly for historical reasons. Consider using pdv_image() or pdv_start_images() instead. More...

uint8_t *	pdv_image (PdvDev pdv_p)
	Start image acquisition if not already started, then wait for and return the address of the next available image. More...

int	pdv_multibuf (PdvDev pdv_p, int numbufs)
	Sets the number of multiple buffers to use in ring buffer continuous mode, and allocates them. This routine allocates the buffers itself, in kernel or low memory as required by the EDT device driver for optimal DMA. More...

void	pdv_start_images (PdvDev pdv_p, int count)
	Starts multiple image acquisition. More...

uint8_t **	pdv_buffer_addresses (PdvDev pdv_p)
	Returns the addresses of the buffers allocated by the last call to pdv_multibuf(). See pdv_wait_images() for a description and example of use. More...

uint8_t *	pdv_wait_images (PdvDev pdv_p, int count)
	Waits for the images started by pdv_start_images. More...

uint8_t *	pdv_wait_images_timed_raw (PdvDev pdv_p, int count, edt_timespec_t *ts, bool skip_deinterleave)
	Waits for one or more images started by pdv_start_images. Optionally controls post-processing and returns a timestamp. More...

uint8_t *	pdv_wait_last_image (PdvDev pdv_p, int *num_skipped)
	Waits for the last image that has been acquired. A convenience wrapper of pdv_wait_last_image_timed_raw(). More...

uint8_t *	pdv_wait_last_image_timed_raw (PdvDev pdv_p, int num_skipped, edt_timespec_t ts, bool skip_deinterleave)
	Waits for the last image that has been acquired. Optionally controls post-processing and returns a timestamp. More...

uint8_t *	pdv_get_last_image (PdvDev pdv_p)
	Returns a pointer to the last image that was acquired (non-blocking). It will return a pointer to the same buffer if called a second time with no new images acquired. More...

uint8_t *	pdv_get_last_image_raw (PdvDev pdv_p)
	Returns a pointer to the last image that was acquired (non-blocking). Identical to the pdv_get_last_image(), except that it skips any image deinterleave method defined by the method_interlace config file directive. More...

uint8_t *	pdv_wait_next_image (PdvDev pdv_p, int *num_skipped)
	Waits for the next image, skipping any previously started images. A convenience wrapper of pdv_wait_next_image_timed_raw(). More...

uint8_t *	pdv_wait_next_image_timed_raw (PdvDev pdv_p, int num_skipped, edt_timespec_t ts, bool skip_deinterleave)
	Waits for the next image, skipping any previously started images. Optionally controls post-processing and returns a timestamp. More...

double	pdv_decode_timestamp (const edt_timespec_t *ts)
	Decode the timestamp from pdv_wait_images_timed_raw and related functions. More...

void	pdv_setup_continuous (PdvDev pdv_p)
	Performs setup for continuous transfers. More...

void	pdv_stop_continuous (PdvDev pdv_p)
	Performs un-setup for continuous transfers. More...

int	pdv_in_continuous (PdvDev pdv_p)
	Gets the status of the continuous flag. More...

void	pdv_flush_fifo (PdvDev pdv_p)
	Flushes the board's input FIFOs, to allow new data transfers to start from a known state. More...

int	pdv_set_timeout (PdvDev pdv_p, int value)
	Sets the length of time to wait for data on acquisition before timing out. More...

int	pdv_get_timeout (PdvDev pdv_p)
	Gets the length of time to wait for data on acquisition before timing out. More...

int	pdv_timeouts (PdvDev pdv_p)
	Returns the number of times the device timed out (frame didn't transfer completely or at all) since the device was opened. More...

int	pdv_timeout_restart (PdvDev pdv_p, int restart)
	Cleans up after a timeout, particularly when you've prestarted multiple buffers or if you've forced a timeout with edt_do_timeout(). More...

int	pdv_overrun (PdvDev pdv_p)
	Determines whether data overran on the last aquire. More...

void	pdv_check_frame (PdvDev pdv_p, uint16_t *image, uint32_t imagesize, int verbose)
	Search an image buffer for a valid frame. If the beginning of the image was not at the start of the image buffer, stop and re-start continuous image aquisition. More...

uint8_t *	pdv_get_interleave_data (PdvDev pdv_p, uint8_t *buf, int bufnum)
	Returns the post-processed data corresponding to a given raw buffer. It does not cause post-processing to happen, it only returns the data if it already exists. More...

int	pdv_get_force_single (PdvDev pdv_p)
	Returns the value of the force_single flag. This flag is 0 by default, and is set by the force_single directive in the config file. More...

void	pdv_set_fval_done (PdvDev pdv_p, int enable)
	Enables frame valid done functionality on the board. More...

int	pdv_get_fval_done (PdvDev pdv_p)
	Returns the frame valid done enable state. More...

int	pdv_get_lines_xferred (PdvDev pdv_p)
	Gets the number of lines transferred during the last acquire. Typically only used in line scan applications where the actual number of lines transferred into a given buffer is unknown at the time of the acquire. More...

int	pdv_get_width_xferred (PdvDev pdv_p)
	Gets the number of pixels transferred during the last line transferred. Typically only used in line scan applications where the actual number of pixels transferred per line may not be known. More...

int	pdv_cl_get_fval_counter (PdvDev pdv_p)
	Gets the number of frame valid transitions that have been seen by the board since the last time the board/channel was initialized or the last time pdv_cl_reset_fval_counter() was called. More...

void	pdv_cl_reset_fval_counter (PdvDev pdv_p)
	Resets the frame valid counter to zero. More...

Detailed Description

Image acquisition subroutines. The simplest way to acquire an image from an EDT digital imaging board is to use pdv_image() (see simplest_take.c for an example).

Using pdv_start_images() / pdv_wait_images() splits image acquisition into queue and retrieve phases, allowing programmers to parallelize image acquisition and processing (see simple_take.c).

Using pdv_start_images() with pdv_wait_images() adds prestart / queuing for further optimization. Other subroutines are provided for more specialized uses (see other simple_*.c example programs).

Image acquisition subroutines such as pdv_wait_images() return the data as a pointer to the image buffer. Images are not framed in any way, the buffer only contains the pixel data. Application programs should use query routines such as pdv_get_width(), pdv_get_height() and pdv_get_depth() to find out the data line or frame size and number of bits per pixel.

The bitwise format of the pixel data will depend on the number of bits per pixel as defined by the camera and configuration file, as well as any data de-interleave or de-mosaicing method (e.g. bayer interpolation) that may be enabled via the config file's method_interlace directive (exception: _raw subroutines bypass data re-ordering). Pixel data for typical formats and re-ordering methods are as follows:

Camera Output	Config Attributes (also see the Camera Configuration guide)	Buffer data
Monochrome 8 bits	depth: 8 extdepth: 8 cl_data_path_norm: 07 (single ch.) or 17 (dual ch.)	1 byte/pixel
Monochrome 10-16 bits	depth: 10, 12, 14 or 16 extdepth: same as depth CL_DATA_PATH_NORM: 09, 0b, 0d or 0f (single ch.), 19, 1b, 1d or 1f (dual ch.)	2 bytes/pixel, msb-justified
Bayer color 8 bits	depth: 24 extdepth: 8 CL_DATA_PATH_NORM: 07 (single ch.), 17 (dual ch.) method_interlace: BGGR	3 bytes/pixel, B G R
Bayer color 10-16 bits	depth: 24 extdepth: 10, 12, 14 or 16 CL_DATA_PATH_NORM: 09, 0b, 0d or 0f (single ch.), 19, 1b, 1d or 1f (dual ch.) method_interlace: BGGR_WORD	3 bytes/pixel, B G R
RGB color 24 bits	depth: 24 extdepth: 24 CL_CFG_NORM: 01	3 bytes/pixel, B G R
RGB color 30 bits	depth: 32 extdepth: 32 rgb30: 1 or 3 CL_CFG_NORM: 01 (note: PCI DV C-Link and PCIe4/8 DVa C-Link boards must be flashed with medium mode FPGA [see the users guide])	4 bytes/pixel, 8B 8G 8R 2B 2G 2R 2x

Function Documentation

◆ pdv_read()

int pdv_read	(	PdvDev	pdv_p,
		unsigned char *	buf,
		unsigned long	size
	)

Reads image data from the EDT framegrabber board. pdv_read is not supported on all platforms and is included mainly for historical reasons. Consider using pdv_image() or pdv_start_images() instead.

Parameters

pdv_p	The open PDV device handle.
buf	The data buffer to receive the image.
size	The size, in bytes, of the data buffer; ordinarily, width * height * bytes per pixel

Returns: The number of bytes read.

See also: pdv_image(), pdv_start_images()

This is the lowest-level method for aquiring an image. We recommend instead setting up ring buffers using pdv_multibuf() and ring buffer subroutines such as pdv_start_images() to do the acquire. pdv_read should never be used when ring buffering is in effect (after calling pdv_multibuf()), or be mixed with ring buffer acquisition commands.

Example:

int size = pdv_get_dma_size(pdv_p);
 
uint8_t *buf = malloc(size);
int bytes_returned = pdv_read(pdv_p, buf, size);

◆ pdv_image()

uint8_t * pdv_image ( PdvDev pdv_p )

Start image acquisition if not already started, then wait for and return the address of the next available image.

Parameters

pdv_p The open PDV device handle.

Returns: The address of the image buffer that has been acquired.

See also: pdv_start_images(), pdv_wait_images()

This routine is the same as doing pdv_start_images(1) followed by pdv_wait_images(1). It is the simplest way to acquire an image, and in single shot applications may be all that is needed. For continuous sequential transfers with fast cameras, particularly when there is processing involved, (including displaying or saving), the separate start / wait calls will usually be necessary in order to avoid skipping images.

The format of the returned data depends on the number of bits per pixel and any post-capture reordering that is enabled via the config file. For detailed information on data formats, see the Acquisition section.

◆ pdv_multibuf()

int pdv_multibuf	(	PdvDev	pdv_p,
		int	numbufs
	)

Sets the number of multiple buffers to use in ring buffer continuous mode, and allocates them. This routine allocates the buffers itself, in kernel or low memory as required by the EDT device driver for optimal DMA.

Parameters

pdv_p	The open PDV device handle.
numbufs	The number of buffers to allocate.

Returns: 0 on success, -1 on failure.

See also: pdv_buffer_addresses()

pdv_multibuf need only be called once after a pdv_open() or pdv_open_channel(), and before any calls to acquisition subroutines such as pdv_start_images() or pdv_wait_images(). If image size changes, call pdv_multibuf() again to re-allocate buffers with the new image size.

The number of buffers is limited only by the amount of host memory available, up to approximately 3.5GBytes (or less, depending on other OS use of the low 3.5 GB of memory). Each buffer has a certain amount of overhead, so setting a large number, even if the images are small, is not recommended. Four is the recommended number: at any time, one buffer is being read in, one buffer is being read out, one is being set up for DMA, and one is in reserve in case of overlap. Additional buffers may be necessary with very fast cameras; 32 will almost always smooth out any problems with really fast cameras, and if the system can't keep up with 64 buffers allocated, there may be other problems.

Note: The ring buffer scheme is designed for one primary purpose: optimal acquisition speed. Programmers should resist the temptation to increase the number of buffers and use them for storage or for processing. Instead use memcpy or equivalent to copy each buffer out after the image has been acquired, and do any processing etc. on the copy.

◆ pdv_start_images()

void pdv_start_images	(	PdvDev	pdv_p,
		int	count
	)

Starts multiple image acquisition.

Parameters

pdv_p	The open PDV device handle.
count	Number of images to start. A value of 0 starts freerun. To stop freerun, call pdv_start_images again with a `count` of 1 or more.

See also: pdv_wait_images(), pdv_multibuf()

Returns without waiting for acquisition to complete. Used with pdv_wait_images which waits for the image to complete and returns a pointer to it.

Queues multiple image acquisitions. Recommended to be used with ring buffering (see pdv_multibuf). Returns without waiting for acquisition to complete. Use pdv_wait_images, or pdv_buffer_addresses to get the address(es) of the acquired image(s).

◆ pdv_buffer_addresses()

uint8_t ** pdv_buffer_addresses ( PdvDev pdv_p )

Returns the addresses of the buffers allocated by the last call to pdv_multibuf(). See pdv_wait_images() for a description and example of use.

Parameters

pdv_p The open PDV device handle.

Returns: An array of pointers to image buffers. The size of the array is equal to the number of buffers allocated.

See also: pdv_multibuf()

◆ pdv_wait_images()

uint8_t * pdv_wait_images	(	PdvDev	pdv_p,
		int	count
	)

Waits for the images started by pdv_start_images.

Parameters

pdv_p	The open PDV device handle.
count	Number of images to wait for before returning. If `count` is greater than the number of buffers set by pdv_multibuf, only the last `count` images will be available when this function returns.

Returns: The address of the last image.

See also: pdv_wait_images_timed_raw()

Returns immediately if all of the images started by the last call to pdv_start_images are complete.

Use pdv_start_images to start image acquisition of a specified number of images and pdv_wait_images to wait for some or all of them to complete. pdv_wait_images returns the address of the last image. If you've used pdv_multibuf to allocate two or more separate image buffers, you can start up to the number of buffers specified by pdv_multibuf, wait for some or all of them to complete, then use pdv_buffer_addresses to get the addresses of the images.

Note: Image data format discussed in pdv_wait_images_timed_raw.

Example:

// see also simple_take.c example program
unsigned char **bufs;
 
pdv_multibuf(pdv_p, 4);
pdv_start_images(pdv_p, 4);
pdv_wait_images(pdv_p, 4);
bufs = pdv_buffer_addresses(pdv_p);
 
for (i=0; i<4; i++)
    process_image(bufs[i]);   // your processing routine

◆ pdv_wait_images_timed_raw()

uint8_t * pdv_wait_images_timed_raw	(	PdvDev	pdv_p,
		int	count,
		edt_timespec_t *	ts,
		bool	skip_deinterleave
	)

Waits for one or more images started by pdv_start_images. Optionally controls post-processing and returns a timestamp.

Parameters

	pdv_p	The open PDV device handle.
	count	Number of images to wait for before returning. If `count` is greater than the number of buffers set by pdv_multibuf, only the last `count` images will be available when this function returns.
[out]	ts	If non-null, returns the time when the last image DMA transfer finished. Pass NULL to skip getting the last image's timestamp.
	skip_deinterleave	If true, any de-interleaving post pocessing will be skipped.

Returns: The address of the last image.

See also: pdv_start_images(), pdv_wait_images(), pdv_decode_timestamp()

Note: pdv_wait_ subroutines wait for all of the image data (as determined by the configured width, height and depth) to be read in before returning. If data loss occurs during the transfer or there is no incoming camera data, the subroutines return (with partial or no data in the buffer) after the image timeout period has expired - see pdv_timeouts(), pdv_set_timeout() and pdv_get_timeout().

Timestamp returned in ts comes from the system clock (gettimeofday) at the time the image transfer from the camera to the host memory (DMA) is finished. Latency between the end of DMA and when the timestamp is made will be on the order of a few microseconds. There are other delays in the chain – the camera may have a lag between the end of frame valid and the end of sending out the data, and system interrupt response time may also be a factor. For more precise timestamping using an external time input, see the PCIe8 DV C-Link Application Note: Using the Timestamp function for IrigB input .

Post-processing is enabled by the method_interlace configuration file directive. When no method_interlace directive is present in the camera configuration file, this subroutine is equivalent to pdv_wait_images.

To get raw image data directly from DMA, bypassing any interleave post-processing, set skip_deinterleave to true.

The format of the returned data depends on the number of bits per pixel and any post-capture reordering that is enabled via the camera config file. For detailed information on data formats, see the Acquisition section. If data reordering is not enabled, the data buffer will be the same whether skip_deinterleave is true or not. For more on data reordering, see the method_interlace configuration directive.

For information about camera configuration directives or data reordering, see the Camera Configuration Guide.

Example:

uint8_t **bufs = NULL;
uint32_t timestamp[2] = {0};
bool skip_deinterleave = true;
int num_images = 4;
 
// Set up multiple buffers for optimal pipelining
pdv_multibuf(pdv_p, num_images);
// Start acquiring all images
pdv_start_images(pdv_p, num_images);
// Wait for all images
pdv_wait_images_timed_raw(pdv_p, num_images, timestamp, skip_deinterleave);
bufs = pdv_buffer_addresses(pdv_p);
printf("Got all images, last one at time: %lf\n", pdv_decode_timestamp(pdv_p, timestamp));
 
for (int i = 0; i < num_images; i++)
    process_image(bufs[i]);   // your processing routine

◆ pdv_wait_last_image()

uint8_t * pdv_wait_last_image	(	PdvDev	pdv_p,
		int *	num_skipped
	)

Waits for the last image that has been acquired. A convenience wrapper of pdv_wait_last_image_timed_raw().

Parameters

	pdv_p	The open PDV device handle.
[out]	num_skipped	Pointer to an integer which will be filled in with number of images skipped, if any. Can be set to NULL to ignore.

Returns: Address of the image.

See also: pdv_start_images(), pdv_wait_images(), pdv_wait_last_image_timed_raw()

Identical to:

pdv_wait_last_image_timed_raw(pdv_p,
                              num_skipped,
                              ts = NULL,
                              skip_deinterleave = false)

Example:

int skipped_frames;
uint8_t *imagebuf;
 
imagebuf = pdv_wait_last_image(pdv_p, &skipped_frames);

◆ pdv_wait_last_image_timed_raw()

uint8_t * pdv_wait_last_image_timed_raw	(	PdvDev	pdv_p,
		int *	num_skipped,
		edt_timespec_t *	ts,
		bool	skip_deinterleave
	)

Waits for the last image that has been acquired. Optionally controls post-processing and returns a timestamp.

Parameters

	pdv_p	The open PDV device handle.
[out]	num_skipped	Pointer to an integer which will be filled in with number of images skipped, if any. Can be set to NULL to ignore.
[out]	ts	If non-null, returns the time when the last image DMA transfer finished. Pass NULL to ignore. See pdv_wait_images_timed_raw for a detailed explanation.
	skip_deinterleave	If true, any de-interleave post pocessing will be skipped.

Returns: The address of the last image.

See also: pdv_start_images(), pdv_wait_images(), pdv_wait_last_image()

This is useful if the display cannot keep up with acquisition and it is not necessary to store all images. If this routine is called for a second time before another image has been acquired, it will block waiting for the next image to complete.

Timestamp and image data descriptions in pdv_wait_images_timed_raw apply to this function.

◆ pdv_get_last_image()

uint8_t * pdv_get_last_image ( PdvDev pdv_p )

Returns a pointer to the last image that was acquired (non-blocking). It will return a pointer to the same buffer if called a second time with no new images acquired.

Parameters

pdv_p The open PDV device handle.

Returns: The address of the last image acquired.

See also: pdv_wait_last_image(), pdv_wait_last_image_timed_raw(), pdv_wait_images(), edt_done_count()

◆ pdv_get_last_image_raw()

uint8_t * pdv_get_last_image_raw ( PdvDev pdv_p )

Returns a pointer to the last image that was acquired (non-blocking). Identical to the pdv_get_last_image(), except that it skips any image deinterleave method defined by the method_interlace config file directive.

Parameters

pdv_p The open PDV device handle.

Returns: The address of the last image acquired.

See also: pdv_get_last_image()

◆ pdv_wait_next_image()

uint8_t * pdv_wait_next_image	(	PdvDev	pdv_p,
		int *	num_skipped
	)

Waits for the next image, skipping any previously started images. A convenience wrapper of pdv_wait_next_image_timed_raw().

Parameters

	pdv_p	The open PDV device handle.
[out]	num_skipped	Pointer to an integer which will be filled in with number of images skipped, if any. Can be set to NULL to ignore.

Returns: The address of the image.

See also: pdv_start_images(), pdv_wait_images(), pdv_wait_next_image_timed_raw()

Identical to:

pdv_wait_next_image_timed_raw(pdv_p,
                              num_skipped,
                              ts = NULL,
                              skip_deinterleave = false)

◆ pdv_wait_next_image_timed_raw()

uint8_t * pdv_wait_next_image_timed_raw	(	PdvDev	pdv_p,
		int *	num_skipped,
		edt_timespec_t *	ts,
		bool	skip_deinterleave
	)

Waits for the next image, skipping any previously started images. Optionally controls post-processing and returns a timestamp.

The format of the returned data and timestamp is described in pdv_wait_images_timed_raw.

Parameters

	pdv_p	The open PDV device handle.
[out]	num_skipped	Pointer to an integer which will be filled in with number of images skipped, if any. Can be set to NULL to ignore.
[out]	ts	If non-null, returns the time when the last image DMA transfer finished. Pass NULL to ignore. See pdv_wait_images_timed_raw for a detailed explanation.
	skip_deinterleave	If true, any de-interleave post processing will be skipped.

Returns: The address of the image.

See also: pdv_start_images(), pdv_wait_images(), pdv_wait_next_image()

◆ pdv_decode_timestamp()

double pdv_decode_timestamp ( const edt_timespec_t * ts )

Decode the timestamp from pdv_wait_images_timed_raw and related functions.

Converts the timestamp returned by the _timed subroutines to floating-point, representing the value in seconds.

Parameters

ts	The timestamp returned from pdv_wait_images_timed_raw or similar function.

Returns: The timestamp as a double-precision floating-point value.

See also: pdv_wait_images_timed_raw(), pdv_wait_last_image_timed_raw(), pdv_wait_next_image_timed_raw()

◆ pdv_setup_continuous()

void pdv_setup_continuous ( PdvDev pdv_p )

Performs setup for continuous transfers.

Shouldn't need to be called by user apps since pdv_start_images(), etc. call it already. But it is in some EDT example applications from before this was the case.

Parameters

pdv_p The open PDV device handle.

See also: pdv_stop_continuous()

◆ pdv_stop_continuous()

void pdv_stop_continuous ( PdvDev pdv_p )

Performs un-setup for continuous transfers.

Shouldn't need to be called by user apps since other subroutines (e.g. pdv_timeout_restart()) now call it as needed. But it is still in some EDT example applications from before this was the case.

Parameters

pdv_p The open PDV device handle.

See also: pdv_setup_continuous()

◆ pdv_in_continuous()

int pdv_in_continuous ( PdvDev pdv_p )

Gets the status of the continuous flag.

Parameters

pdv_p The open PDV device handle.

Returns: 1 if continuous, 0 if not.

See also: pdv_setup_continuous(), pdv_stop_continuous()

◆ pdv_flush_fifo()

void pdv_flush_fifo ( PdvDev pdv_p )

Flushes the board's input FIFOs, to allow new data transfers to start from a known state.

This subroutine effectively resets the board, so calling it after every image will degrade performance and is not recommended. Additionally, resetting after a timeout, involves more than just flushing the FIFOs – therefore we recommend using pdv_timeout_restart() to reset (which calls this, among other things).

Parameters

pdv_p The open PDV device handle.

◆ pdv_set_timeout()

int pdv_set_timeout	(	PdvDev	pdv_p,
		int	value
	)

Sets the length of time to wait for data on acquisition before timing out.

Parameters

pdv_p	The open PDV device handle.
value	`> 0` – The number of milliseconds to wait for timeout. `0` – Block forever waiting for data. `-1` – Revert to automatic timeouts.

Returns: 0 on success, -1 on failure.

See also: user_timeout directive in the Camera Configuration Guide

The default timeout value is set at initcam time and recalculated / updated whenever pdv_set_exposure is called. Calling this routine with a value of 0 or greater overrides the automatic value. If called with a value of 0, acquisition routines such as pdv_image() or pdv_wait_images() will wait forever for (block) the amount of data requested. A value between 0 and 65535 sets the timeout to a fixed time (millisecond units). A value of -1 tells the driver to revert to the automatically calculated value.

◆ pdv_get_timeout()

int pdv_get_timeout ( PdvDev pdv_p )

Gets the length of time to wait for data on acquisition before timing out.

Parameters

pdv_p The open PDV device handle.

Returns: The timeout value, in milliseconds.

◆ pdv_timeouts()

int pdv_timeouts ( PdvDev pdv_p )

Returns the number of times the device timed out (frame didn't transfer completely or at all) since the device was opened.

Parameters

pdv_p The open PDV device handle.

Returns: The number of timeouts since the device was opened.

See also: pdv_set_timeout(), pdv_get_timeout(), pdv_timeout_restart(), pdv_enable_framesync()

Timeouts occur when some or all of the image failed to transfer. Reasons for this range from an unplugged cable to misconfiguration to system bandwidth saturation. If broken images, slow frame rates or blank images are encountered, it will usually be associated with an image timeout.

Frequent timeouts can be a result of the board being in a non-optimal bus slot or other system-related issues. This is especially true with legacy PCI devices such as the PCI DV C-Link. For more information on optimizing your configuration (and system requirements in general) see EDT's System Requirements web page.

A robust application will check to see whether the timeout counter has increased after every new acquire, and take appropriate action. Since timeouts are often associated with data overruns or underruns, they frequently indicate an out-of-synch condtion. So for continuous captures, applications should perform a reset and restart following detection of a timeout, by calling pdv_timeout_restart().

Various factors can prevent timeouts from being reported when data is dropped. With some versions of board firmware, if a small amount of data is lost on a line, the board's region-of-interest (ROI) logic will fill in the missing data using blanking between lines, preventing a timeout from occurring (but still resulting in an out-of-synch frame.) This situation can usually be rectified by updating the board firmware, since the new versions (e.g. PCIe board FW versions 14 and later) have the blanking feature disabled by default.

Hardware continuous mode (enabled via the fv_once or hardware_continuous config file directives) can be problmatic for timeouts. Since these modes cause the board to ignore all FVAL (frame start) signals beyond the first one in a continuous sequence, losses of relatively small amounts of data won't trigger a timeout, resulting in a persistently out-of-synch condition. The framesync footer logic shown in the simple_irig2.c example application was designed as a workaround for this, and more recently (e.g. driver/library versions 5.3.9.4 and later) the framesync logic was incorporated into pdv_timeouts, providing a convenient and transparent way to ensure detection of and recovery from an out-of-synch condition without the need to change any code. See pdv_enable_framesync() and the the method_framesync directive in the Camera Configuration Guide for more on this.

Example:

int t, last_timeouts = 0;
 
t = pdv_timeouts(pdv_p);
if (t > last_timeouts)
{
  printf("got timeout\n");
 
  // (add recovery code here -- see simple_take.c for example)
 
  last_timeouts = t;
}

◆ pdv_timeout_restart()

int pdv_timeout_restart	(	PdvDev	pdv_p,
		int	restart
	)

Cleans up after a timeout, particularly when you've prestarted multiple buffers or if you've forced a timeout with edt_do_timeout().

Parameters

pdv_p	The open PDV device handle.
restart	Whether to immediately restart acquiring.

Returns: The number of buffers left undone.

See also: pdv_timeouts()

The example program simple_take.c uses this function; note that it calls pdv_timeout_restart() twice, which may be overkill for some applications/cameras. If the system is configured properly (and all cables/ cameras have robust connections), timeouts should not be a factor. Even so, a robust app will handle timeouts gracefully so it is a good idea to experiment with various timeout recovery methods to make sure you have something that works for your situation.

The return value is the number of unfinished buffers. It can be used as argument to pdv_start_images() if the calling routine wants to restart the pipeline as if nothing happened.

◆ pdv_overrun()

int pdv_overrun ( PdvDev pdv_p )

Determines whether data overran on the last aquire.

Parameters

pdv_p The open PDV device handle.

Returns: The number of bytes of data remaining from last aquire. 0 indicates no overrun.

◆ pdv_check_frame()

void pdv_check_frame	(	PdvDev	pdv_p,
		uint16_t *	image,
		uint32_t	imagesize,
		int	verbose
	)

Search an image buffer for a valid frame. If the beginning of the image was not at the start of the image buffer, stop and re-start continuous image aquisition.

Parameters

pdv_p	The open PDV device handle.
image	Image buffer to inspect.
imagesize	Total size (in bytes) of the image in `imagebuf`.
verbose	Pass `true` (1) to enable more log messages.

◆ pdv_get_interleave_data()

uint8_t * pdv_get_interleave_data	(	PdvDev	pdv_p,
		uint8_t *	buf,
		int	bufnum
	)

Returns the post-processed data corresponding to a given raw buffer. It does not cause post-processing to happen, it only returns the data if it already exists.

Parameters

pdv_p	The open PDV device handle.
buf	A pointer to the raw data buffer.
bufnum	The index of the data buffer in the buffer array.

Returns: A pointer to the post-processed buffer.

◆ pdv_get_force_single()

int pdv_get_force_single ( PdvDev pdv_p )

Returns the value of the force_single flag. This flag is 0 by default, and is set by the force_single directive in the config file.

Parameters

pdv_p The open PDV device handle.

Returns: Value of the force_single flag.

See also: pdv_multibuf(), force_single camera configuration directive.

This flag is generally set in cases where the camera uses a trigger method that will violate the pipelining of multiple ring buffers. Most cameras are either continuous, or triggered from the frame grabber, or triggered externally through a trigger line, and won't have this flag set. But a very few cameras use a serial command or similar to trigger the camera, and possibly require a response to be read, in which case the parallel scheme won't work. It is for such cases that this variable is meant to be used. In these cases, the application should allocate only a single buffer (pdv_multibuf(pdv_p, 1)), and should never pre-start more than one buffer before waiting for it.

The simple_take.c example demonstrates use of this routine.

◆ pdv_set_fval_done()

void pdv_set_fval_done	(	PdvDev	pdv_p,
		int	enable
	)

Enables frame valid done functionality on the board.

Parameters

pdv_p	The open PDV device handle.
enable	Whether to enable of disable frame valid done.

See also: pdv_get_lines_xferred(), fval_done directive in the Camera Configuration Guide

In most area scan and many line scan applications, the number of lines in the image is known beforehand. EDT boards start reading pixels in when FRAME VALID signal goes TRUE, but as an optimization measure, they ignore the frame valid FALSE and instead return when the expected number of pixels have been read in.

However when the number of lines is not known beforehand (for example in a mail scanner with a sensor that detects the start/end of packages) it becomes necessary to enable image termination on the Frame Valid. This subroutine enables that functionality.

When using this, the number of lines (height directive in the configuration file) should be equal to or greater than the largest possible number of lines that will be read in and the ring buffers should be big enough to accomodate the largest possible image. Otherwise, frames will be split across separate buffers.

use pdv_get_lines_xferred() after the acquisition returns to find out how many lines actually transferred.

Note: If the fval_done: 1 directive is present in the configuration file (preferred), this subroutine to be called with enable=1 during initialization and it will not be necessary to call it from an application.

◆ pdv_get_fval_done()

int pdv_get_fval_done ( PdvDev pdv_p )

Returns the frame valid done enable state.

Parameters

pdv_p The open PDV device handle.

Returns: Whether the frame valid done feature is enabled.

See also: pdv_set_fval_done()

◆ pdv_get_lines_xferred()

int pdv_get_lines_xferred ( PdvDev pdv_p )

Gets the number of lines transferred during the last acquire. Typically only used in line scan applications where the actual number of lines transferred into a given buffer is unknown at the time of the acquire.

Note that if acquires are continuously being queued (as in pdv_start_images(pdv_p, n) where n is greater than 1), the number of lines tranferred may not reflect the last finished acquire.

Parameters

pdv_p The open PDV device handle.

Returns: The number of lines transferred on the last acquire.

See also: pdv_get_width_xferred()

◆ pdv_get_width_xferred()

int pdv_get_width_xferred ( PdvDev pdv_p )

Gets the number of pixels transferred during the last line transferred. Typically only used in line scan applications where the actual number of pixels transferred per line may not be known.

Note that if lines are continuously being transferred (the normal case), the number of pixels tranferred may not reflect the last finished line.

Parameters

pdv_p The open PDV device handle.

Returns: The number of pixels transferred on the last line.

See also: pdv_get_lines_xferred()

◆ pdv_cl_get_fval_counter()

int pdv_cl_get_fval_counter ( PdvDev pdv_p )

Gets the number of frame valid transitions that have been seen by the board since the last time the board/channel was initialized or the last time pdv_cl_reset_fval_counter() was called.

The number returned is NOT the number of frames read in; the counter on the board counts all frame ticks seen whether images are being read in or not. As such this subroutine can be useful in determining whether a camera is connected (among other things), assuming that the camera is a freerun camera or has a continuous external trigger.

Parameters

pdv_p The open PDV device handle.

Returns: The number of frame valid transitions seen.

See also: pdv_cl_reset_fval_counter()

◆ pdv_cl_reset_fval_counter()

void pdv_cl_reset_fval_counter ( PdvDev pdv_p )

Resets the frame valid counter to zero.

Parameters

pdv_p The open PDV device handle.

See also: pdv_cl_get_fval_counter()

Functions

Detailed Description

Function Documentation

◆ pdv_read()

◆ pdv_image()

◆ pdv_multibuf()

◆ pdv_start_images()

◆ pdv_buffer_addresses()

◆ pdv_wait_images()

◆ pdv_wait_images_timed_raw()

◆ pdv_wait_last_image()

◆ pdv_wait_last_image_timed_raw()

◆ pdv_get_last_image()

◆ pdv_get_last_image_raw()

◆ pdv_wait_next_image()

◆ pdv_wait_next_image_timed_raw()

◆ pdv_decode_timestamp()

◆ pdv_setup_continuous()

◆ pdv_stop_continuous()

◆ pdv_in_continuous()

◆ pdv_flush_fifo()

◆ pdv_set_timeout()

◆ pdv_get_timeout()

◆ pdv_timeouts()

◆ pdv_timeout_restart()

◆ pdv_overrun()

◆ pdv_check_frame()

◆ pdv_get_interleave_data()

◆ pdv_get_force_single()

◆ pdv_set_fval_done()

◆ pdv_get_fval_done()

◆ pdv_get_lines_xferred()

◆ pdv_get_width_xferred()

◆ pdv_cl_get_fval_counter()

◆ pdv_cl_reset_fval_counter()