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_image / pdv_wait_image 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 (or pdv_wait_image) 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_image 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 deinterleave or demosaicing 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 |
Functions | |
| u_char ** | pdv_buffer_addresses (PdvDev *pdv_p) |
| Returns the addresses of the buffers allocated by the last call to pdv_multibuf or pdv_set_buffers. | |
| int | pdv_cl_get_fv_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_fv_counter was called. | |
| void | pdv_cl_reset_fv_counter (PdvDev *pdv_p) |
| Resets the frame valid counter to zero. | |
| void | pdv_flush_channel_fifo (PdvDev *pdv_p) |
| OBSOLETE: just use pdv_flush_fifo(pdv_p) now. | |
| void | pdv_flush_fifo (PdvDev *pdv_p) |
| FIX !!! Write brief comment for pdv_flush_fifo here. | |
| int | pdv_force_single (PdvDev *pdv_p) |
| Returns the value of the force_single flag. | |
| u_char * | pdv_get_last_image (PdvDev *pdv_p) |
| Returns a pointer to the last image that was acquired (non-blocking). | |
| u_char * | pdv_get_last_raw (PdvDev *pdv_p) |
| get last raw image. | |
| int | pdv_get_lines_xferred (PdvDev *pdv_p) |
| Gets the number of lines transferred during the last acquire. | |
| int | pdv_get_timeout (PdvDev *pdv_p) |
| Gets the length of time to wait for data on acquisition before timing out. | |
| int | pdv_get_width_xferred (PdvDev *pdv_p) |
| Gets the number of pixels transferred during the last line transferred. | |
| unsigned char * | pdv_image (PdvDev *pdv_p) |
| Start image acquisition if not already started, then wait for and return the address of the next available image. | |
| unsigned char * | pdv_image_raw (PdvDev *pdv_p) |
| Start image acquisition if not already started, then wait for and return the address of the next available image (unprocessed). | |
| int | pdv_in_continuous (PdvDev *pdv_p) |
| Gets the status of the continuous flag. | |
| int | pdv_interlace_method (PdvDev *pdv_p) |
| Returns the interlace method, as set from the method_interlace directive in the configuration file [from pdv_initcam]. | |
| unsigned char * | pdv_last_image_timed (PdvDev *pdv_p, u_int *timep) |
| Identical to pdv_wait_last_image_timed; included for backwards compatability only. | |
| unsigned char * | pdv_last_image_timed_raw (PdvDev *pdv_p, u_int *timep, int doRaw) |
| Identical to pdv_wait_last_image_timed_raw; included for backwards compatability only. | |
| int | pdv_multibuf (PdvDev *pdv_p, int numbufs) |
| Sets the number of multiple buffers to use in ring buffer continuous mode, and allocates them. | |
| int | pdv_overrun (PdvDev *pdv_p) |
| Determines whether data overran on the last aquire. | |
| int | pdv_read (PdvDev *pdv_p, unsigned char *buf, unsigned long size) |
| Reads image data from the EDT framegrabber board. | |
| int | pdv_set_buffers (PdvDev *pdv_p, int numbufs, unsigned char **bufarray) |
| Used to set up user-allocated buffers to be used in ring buffer mode, cannot be used on systems that have more than 3.5GB/memory (ie the subroutine has been depricated for all practical purposes, instead use pdv_multibuf). | |
| void | pdv_set_fval_done (PdvDev *pdv_p, int enable) |
| Enables frame valid done functionality on the board. | |
| int | pdv_set_timeout (PdvDev *pdv_p, int value) |
| Sets the length of time to wait for data on acquisition before timing out. | |
| void | pdv_setup_continuous (PdvDev *pdv_p) |
| Performs setup for continuous transfers. | |
| void | pdv_setup_continuous_channel (PdvDev *pdv_p) |
| Obsolete. | |
| void | pdv_setup_dma (PdvDev *pdv_p) |
| Sets up device for DMA. | |
| void | pdv_start_expose (PdvDev *pdv_p) |
| Start expose independent of grab - only works in continuous mode. | |
| void | pdv_start_hardware_continuous (PdvDev *pdv_p) |
| Starts hardware continuous mode. | |
| void | pdv_start_image (PdvDev *pdv_p) |
| Starts acquisition of a single image. | |
| void | pdv_start_images (PdvDev *pdv_p, int count) |
| Starts multiple image acquisition. | |
| void | pdv_stop_continuous (PdvDev *pdv_p) |
| Performs un-setup for continuous transfers. | |
| void | pdv_stop_hardware_continuous (PdvDev *pdv_p) |
| Stops hardware continous mode. | |
| int | pdv_timeout_cleanup (PdvDev *pdv_p) |
| Cleans up after a timeout, particularly when you've prestarted multiple buffers or if you've forced a timeout with edt_do_timeout. | |
| 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. | |
| 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. | |
| unsigned char * | pdv_wait_image (PdvDev *pdv_p) |
| Wait for the image started by pdv_start_image, or for the next image started by pdv_start_images. | |
| unsigned char * | pdv_wait_image_raw (PdvDev *pdv_p) |
| Identical to pdv_wait_image, except image data is returned directly from DMA, bypassing any post-processing that may be in effect. | |
| unsigned char * | pdv_wait_image_timed (PdvDev *pdv_p, u_int *timep) |
| Identical to pdv_wait_image but also returns the time at which the DMA was complete on this image. | |
| unsigned char * | pdv_wait_image_timed_raw (PdvDev *pdv_p, u_int *timep, int doRaw) |
| Identical to pdv_wait_image_timed, except the new argument doRaw specifies whether or not to perform the deinterleave. | |
| u_char * | pdv_wait_images (PdvDev *pdv_p, int count) |
| Waits for the images started by pdv_start_images. | |
| unsigned char * | pdv_wait_images_raw (PdvDev *pdv_p, int count) |
| Identical to the pdv_wait_images, except that it skips any image deinterleave method defined by the method_interlace config file directive. | |
| unsigned char * | pdv_wait_images_timed (PdvDev *pdv_p, int count, u_int *timep) |
| Identical to pdv_wait_images but also returns the time at which the DMA was complete on the last image. | |
| unsigned char * | pdv_wait_images_timed_raw (PdvDev *pdv_p, int count, u_int *timep, int doRaw) |
| Identical to pdv_wait_images_timed, except the new argument doRaw specifies whether or not to perform the deinterleave. | |
| unsigned char * | pdv_wait_last_image (PdvDev *pdv_p, int *nSkipped) |
| Waits for the last image that has been acquired. | |
| unsigned char * | pdv_wait_last_image_raw (PdvDev *pdv_p, int *nSkipped, int doRaw) |
| Identical to the pdv_wait_last_image, except that it provides a way to determine whether to include or bypass any image deinterleave that is enabled. | |
| unsigned char * | pdv_wait_last_image_timed (PdvDev *pdv_p, u_int *timep) |
| Identical to pdv_wait_last_image, but also returns the time at which the DMA was complete on the last image. | |
| unsigned char * | pdv_wait_last_image_timed_raw (PdvDev *pdv_p, u_int *timep, int doRaw) |
| Identical to pdv_wait_last_image_raw but also returns the time at which the DMA was complete on the last image. | |
| unsigned char * | pdv_wait_next_image (PdvDev *pdv_p, int *nSkipped) |
| Waits for the next image, skipping any previously started images. | |
| unsigned char * | pdv_wait_next_image_raw (PdvDev *pdv_p, int *nSkipped, int doRaw) |
| Identical to the pdv_wait_next_image, except that it provides a way to include or bypass any image deinterleave method defined by the method_interlace config file directive. | |
| u_char** pdv_buffer_addresses | ( | PdvDev * | pdv_p | ) |
Returns the addresses of the buffers allocated by the last call to pdv_multibuf or pdv_set_buffers.
See pdv_wait_images for a description and example of use.
| pdv_p | pointer to pdv device structure returned by pdv_open |
| int pdv_cl_get_fv_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_fv_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.
| void pdv_cl_reset_fv_counter | ( | PdvDev * | pdv_p | ) |
| void pdv_flush_fifo | ( | PdvDev * | pdv_p | ) |
| int pdv_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 (see Camera Configuration Guide). 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 take.c program has an example of use of this routine.
| pdv_p | pointer to pdv device structure returned by pdv_open |
| u_char* 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.
| pdv_p | pointer to pdv device structure returned by pdv_open |
| u_char* pdv_get_last_raw | ( | PdvDev * | pdv_p | ) |
get last raw image.
Identical to the pdv_get_last_image, except that it skips any image deinterleave method defined by the method_interlace config file directive.
| pdv_p | pointer to pdv device structure returned by pdv_open |
| 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 (see also fval_done config file directive.) an interrupt (such as from an external sensor) that tells the device to stop acquiring before a full buffer has been read in. 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.
| int pdv_get_timeout | ( | PdvDev * | pdv_p | ) |
Gets the length of time to wait for data on acquisition before timing out.
A default time value for this is calculated based on the size of the image produced by the camera in use and set by pdv_open. If this value is 0, acquisition routines such as pdv_image and pdv_wait_image will wait forever for (block) the amount of data requested.
| pdv_p | pointer to pdv device structure returned by pdv_open |
| 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 (see also fval_done config file directive.) an interrupt (such as from an external sensor) that tells the device to stop acquiring before a full buffer has been read in. Note that if lines are continuously being transferred (the normal case), the number of pixels tranferred may not reflect the last finished line.
| unsigned char* pdv_image | ( | PdvDev * | pdv_p | ) |
Start image acquisition if not already started, then wait for and return the address of the next available image.
This routine is the same as doing a pdv_start_image followed by pdv_wait_image. 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_p | pointer to pdv device structure returned by pdv_open |
| unsigned char* pdv_image_raw | ( | PdvDev * | pdv_p | ) |
Start image acquisition if not already started, then wait for and return the address of the next available image (unprocessed).
This routine is the same as pdv_image but skips the deinterleave step (if enabled via the method_interlace config file directive).
| pdv_p | device struct returned from pdv_open |
| int pdv_in_continuous | ( | PdvDev * | pdv_p | ) |
Gets the status of the continuous flag.
| pdv_p | pointer to pdv device structure returned by pdv_open |
| int pdv_interlace_method | ( | PdvDev * | pdv_p | ) |
Returns the interlace method, as set from the method_interlace directive in the configuration file [from pdv_initcam].
This method is used to determine how the image data will be rearranged (if at all) before being returned from pdv_wait_images or pdv_read.
For more on deinterleave methods, see the Camera Configuration Guide.
_raw acquisition routines bypass the deinterleave logic.| pdv_p | pointer to pdv device structure returned by pdv_open |
| 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.
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 / 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.
| int pdv_overrun | ( | PdvDev * | pdv_p | ) |
| int pdv_read | ( | PdvDev * | pdv_p, | |
| unsigned char * | buf, | |||
| unsigned long | size | |||
| ) |
Reads image data from the EDT framegrabber board.
This is the lowest-level method for aquiring an image. pdv_read is not supported on all platforms; and is included mainly for historical reasons; we recommend instead setting up ring buffers using pdv_multibuf and ring buffer subroutines such as pdv_start_image 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.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| buf | data buffer. | |
| size | size, in bytes, of the data buffer; ordinarily, width * height * bytes per pixel |
int size = pdv_get_dmasize(pdv_p) ; unsigned char *buf = malloc(size); int bytes_returned; bytes_returned = pdv_read(pdv_p, buf, size;
| int pdv_set_buffers | ( | PdvDev * | pdv_p, | |
| int | numbufs, | |||
| unsigned char ** | bufarray | |||
| ) |
Used to set up user-allocated buffers to be used in ring buffer mode, cannot be used on systems that have more than 3.5GB/memory (ie the subroutine has been depricated for all practical purposes, instead use pdv_multibuf).
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| numbufs | number of buffers. Must be 1 or greater. Four is recommended for most applications. | |
| bufarray | If NULL, the library allocates a set of page-aligned ring buffers. If not NULL, this argument is an array of pointers to application-allocated buffers; these buffers must match the size returned by pdv_image_size and number of buffers specified in this call and will be used as the ring buffers. |
int size = pdv_image_size(pdv_p); unsigned char *bufarray[4]; for (i=0; i < 4; i++) bufarray[i] = pdv_alloc(size); pdv_set_buffers(pdv_p, 4, bufarray);
| void pdv_set_fval_done | ( | PdvDev * | pdv_p, | |
| int | enable | |||
| ) |
Enables frame valid done functionality on the board.
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.
| int pdv_set_timeout | ( | PdvDev * | pdv_p, | |
| int | value | |||
| ) |
Sets the length of time to wait for data on acquisition before timing out.
The default timeout value is set at initcam time and recalculated / updated whenever pdv_set_exposure is called (see pdv_auto_set_timeout). 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 and pdv_wait_image 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_p | pointer to pdv device structure returned by pdv_open | |
| value | the number of milliseconds to wait for timeout, or 0 to block waiting for data, or -1 to revert to automatic timeouts |
| 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.
| void pdv_setup_continuous_channel | ( | PdvDev * | pdv_p | ) |
| void pdv_setup_dma | ( | PdvDev * | pdv_p | ) |
| void pdv_start_expose | ( | PdvDev * | pdv_p | ) |
| void pdv_start_hardware_continuous | ( | PdvDev * | pdv_p | ) |
Starts hardware continuous mode.
When hardware continuous mode is enabled, the hardware waits until the first acquisition request, and starts reading data when it sees the camera's first FRAME VALID signal going TRUE. Subsequent frames are read in without regard to the state of FRAME VALID, and LINE VALID (and DATA VALID) are depended upon to gate the data.
This functionality is necessary in some cases where the interframe gap is too small for the OS/device driver to be able to respond for images, typically with very high frame rate cameras. The downside to this is that if data is ever dropped as a result of bandwidth saturation or an unplugged cable for example, frame synch will be forever lost, and cannot be regained without either operator intervention or some intelligent image recognition software. Therefore this mode should only be used when it is certain that it is needed.
| pdv_p | device struct returned from pdv_open |
| void pdv_start_image | ( | PdvDev * | pdv_p | ) |
Starts acquisition of a single image.
Returns without waiting for acquisition to complete. Used with pdv_wait_image, which waits for the image to complete and returns a pointer to it. pdv_start_image(pdv_p) is equivalent to pdv_start_images(pdv_p, 1).
| pdv_p | pointer to pdv device structure returned by pdv_open |
| void pdv_start_images | ( | PdvDev * | pdv_p, | |
| int | count | |||
| ) |
Starts multiple image acquisition.
Queues multiple image acquisitions. Recommended to be used with ring buffering (see pdv_multibuf). Returns without waiting for acquisition to complete. Use pdv_wait_image, pdv_wait_images, or pdv_buffer_addresses to get the address(es) of the acquired image(s).
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| 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. |
| 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_cleanup) now call it as needed. But it is still in some EDT example applications from before this was the case.
| void pdv_stop_hardware_continuous | ( | PdvDev * | pdv_p | ) |
Stops hardware continous mode.
See pdv_start_hardware_continuous for further description.
| pdv_p | device struct returned from pdv_open |
| int pdv_timeout_cleanup | ( | PdvDev * | pdv_p | ) |
Cleans up after a timeout, particularly when you've prestarted multiple buffers or if you've forced a timeout with edt_do_timeout.
Superseded by pdv_timeout_restart with newer boards such as the VisionLink and PCIe series.
| pdv_p | pointer to pdv device structure returned by pdv_open |
| 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.
The example programs take.c and simple_take.c have examples of use; note that these examples call 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.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| restart | whether to immediately restart acquiring. |
| 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.
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 pdv_start_hardware_continuous or 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.
| pdv_p | pointer to pdv device structure returned by pdv_open |
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; }
| unsigned char* pdv_wait_image | ( | PdvDev * | pdv_p | ) |
Wait for the image started by pdv_start_image, or for the next image started by pdv_start_images.
Returns immediately if the image started by the last call to pdv_start_image is already complete.
Use pdv_start_image to start image acquisition, and pdv_wait_image to wait for it to complete. pdv_wait_image returns the address of the image. You can start a second image while processing the first if you've used pdv_multibuf to allocate two or more separate image buffers.
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, pdv_get_timeout, and pdv_auto_set_timeout.
| pdv_p | pointer to pdv device structure returned by pdv_open |
//see also simple_take.c and simplest_take.c example program. pdv_multibuf(pdv_p, 4); pdv_start_image(pdv_p); while(1) { unsigned char *image; image = pdv_wait_image(pdv_p); //returns the latest image pdv_start_image(pdv_p); //start acquisition of next image //process and/or display image previously acquired here printf("got image\n"); }
| unsigned char* pdv_wait_image_raw | ( | PdvDev * | pdv_p | ) |
Identical to pdv_wait_image, except image data is returned directly from DMA, bypassing any post-processing that may be in effect.
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_image.
For information about camera configuration directives, see the Camera Configuration Guide.
| pdv_p | pointer to pdv device structure returned by pdv_open |
pdv_multibuf(pdv_p, 4); pdv_start_image(pdv_p); while(1) { unsigned char *image; image = pdv_wait_image_raw(pdv_p); //returns the latest image pdv_start_image(pdv_p); //start acquisition of next image //process and/or display image previously acquired here printf("got raw image\n"); }
| unsigned char* pdv_wait_image_timed | ( | PdvDev * | pdv_p, | |
| u_int * | timep | |||
| ) |
Identical to pdv_wait_image but also returns the time at which the DMA was complete on this image.
The argument timep should point to an array of unsigned integers which will be filled in with the seconds and microseconds of the time the image was finished being acquired.
Timestamp 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 to 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.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| timep | a pointer to an array of at least two unsigned integers. |
u_int timestamp[2]; pdv_multibuf(pdv_p, 4); pdv_start_image(pdv_p); while(1) { unsigned char *image; // get the latest image image = pdv_wait_image_timed(pdv_p, timestamp); pdv_start_image(pdv_p); //start acquisition of next image //process and/or display image previously acquired here printf("got image, at time %u\n", timestamp); }
| unsigned char* pdv_wait_image_timed_raw | ( | PdvDev * | pdv_p, | |
| u_int * | timep, | |||
| int | doRaw | |||
| ) |
Identical to pdv_wait_image_timed, except the new argument doRaw specifies whether or not to perform the deinterleave.
If the doRaw option is 0, the deinterleave conversion will be performed; if the doRaw option is 1, the deinterleave conversion will not be performed.
Timestamp 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 to 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.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| timep | a pointer to an array of at least two unsigned integers. | |
| doRaw | specifies raw (if 1) or interleaved (if 0) image data. |
u_int timestamp[2]; pdv_multibuf(pdv_p, 4); pdv_start_image(pdv_p); while(1) { unsigned char *image; // get the latest image image = pdv_wait_image_timed_raw(pdv_p, timestamp, 1); pdv_start_image(pdv_p); //start acquisition of next image //process and/or display image previously acquired here printf("got raw image, at time %u\n", timestamp); }
| u_char* pdv_wait_images | ( | PdvDev * | pdv_p, | |
| int | count | |||
| ) |
Waits for the images started by pdv_start_images.
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 specificed 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.
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, pdv_get_timeout, and pdv_auto_set_timeout.| pdv_p | pointer to pdv device structure returned by pdv_open | |
| 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 pdv_wait_images returns. |
// 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 }
| unsigned char* pdv_wait_images_raw | ( | PdvDev * | pdv_p, | |
| int | count | |||
| ) |
Identical to the pdv_wait_images, except that it skips any image deinterleave method defined by the method_interlace config file directive.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| 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. |
// see also simple_take.c example program unsigned char **bufs; pdv_multibuf(pdv_p, 4); pdv_start_images(pdv_p, 4); pdv_wait_images_raw(pdv_p, 4); bufs = pdv_buffer_addresses(pdv_p); for (i=0; i<4; i++) process_image(bufs[i]); // your processing routine }
| unsigned char* pdv_wait_images_timed | ( | PdvDev * | pdv_p, | |
| int | count, | |||
| u_int * | timep | |||
| ) |
Identical to pdv_wait_images but also returns the time at which the DMA was complete on the last image.
The argument timep should point to an array of at least two unsigned integers which will be filled in with the seconds and microseconds of the time the last image was finished being acquired.
Timestamp 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 to 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.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| 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. | |
| timep | a pointer to an array of at least two unsigned integers. |
| unsigned char* pdv_wait_images_timed_raw | ( | PdvDev * | pdv_p, | |
| int | count, | |||
| u_int * | timep, | |||
| int | doRaw | |||
| ) |
Identical to pdv_wait_images_timed, except the new argument doRaw specifies whether or not to perform the deinterleave.
If the doRaw option is 0, the deinterleave conversion will be performed; if the doRaw option is 1, the deinterleave conversion will not be performed.
Timestamp 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 to 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.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| 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. | |
| timep | a pointer to an array of at least two unsigned integers. | |
| doRaw | specifies raw (if 1) or interleaved (if 0) image data. |
unsigned char **bufs; unsigned int timestamp[2]; int doRaw = 1; // true int number_of_images = 4; pdv_multibuf(pdv_p, num_images); pdv_start_images(pdv_p, num_images); pdv_wait_images_timed_raw(pdv_p, num_images, timestamp, doRaw); bufs = pdv_buffer_addresses(pdv_p); printf("got all images. last one at time: %u\n", timestamp); for (i=0; i<4; i++) process_image(bufs[i]); // your processing routine }
| unsigned char* pdv_wait_last_image | ( | PdvDev * | pdv_p, | |
| int * | nSkipped | |||
| ) |
Waits for the last image that has been acquired.
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.
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_p | pointer to pdv device structure returned by pdv_open | |
| nSkipped | pointer to an integer which will be filled in with number of images skipped, if any. |
int skipped_frames; u_char *imagebuf; imagebuf=pdv_wait_last_image(pdv_p &skipped_frames);
| unsigned char* pdv_wait_last_image_raw | ( | PdvDev * | pdv_p, | |
| int * | nSkipped, | |||
| int | doRaw | |||
| ) |
Identical to the pdv_wait_last_image, except that it provides a way to determine whether to include or bypass any image deinterleave that is enabled.
If data reordering is not enabled, the data buffer will be the same whether doRaw is 0 or 1. For more on data reordering, see the method_interlace directive in the Camera Configuration Guide.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| nSkipped | pointer to an integer which will be filled in with number of images skipped, if any. | |
| doRaw | specifies raw (if 1) or interleaved (if 0) image data. |
| unsigned char* pdv_wait_last_image_timed | ( | PdvDev * | pdv_p, | |
| u_int * | timep | |||
| ) |
Identical to pdv_wait_last_image, but also returns the time at which the DMA was complete on the last image.
The argument timep should point to an array of at least two unsigned integers which will be filled in with the seconds and microseconds of the time the last image was finished being acquired.
Timestamp 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 to 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.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| timep | a pointer to an array of at least two unsigned integers. |
| unsigned char* pdv_wait_last_image_timed_raw | ( | PdvDev * | pdv_p, | |
| u_int * | timep, | |||
| int | doRaw | |||
| ) |
Identical to pdv_wait_last_image_raw but also returns the time at which the DMA was complete on the last image.
The argument timep should point to an array of at least two unsigned integers which will be filled in with the seconds and microseconds of the time the last image was finished being acquired.
Timestamp 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 to 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.
If reordering is not enabled, the data buffer will be the same whether doRaw is 0 or 1. For more on data reordering, see the method_interlace directive in the Camera Configuration Guide.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| timep | a pointer to an array of at least two unsigned integers. | |
| doRaw | specifies raw (if 1) or interleaved (if 0). |
| unsigned char* pdv_wait_next_image | ( | PdvDev * | pdv_p, | |
| int * | nSkipped | |||
| ) |
Waits for the next image, skipping any previously started 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_p | pointer to pdv device structure returned by pdv_open | |
| nSkipped | pointer to an integer which will be filled in with number of images skipped, if any. |
| unsigned char* pdv_wait_next_image_raw | ( | PdvDev * | pdv_p, | |
| int * | nSkipped, | |||
| int | doRaw | |||
| ) |
Identical to the pdv_wait_next_image, except that it provides a way to include or bypass any image deinterleave method defined by the method_interlace config file directive.
If data reordering is not enabled, the data buffer will be the same whether doRaw is 0 or 1. For more on data reordering, see the method_interlace directive in the Camera Configuration Guide.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| nSkipped | pointer to an integer which will be filled in with number of images skipped, if any. | |
| doRaw | specifies raw (if 1) or interleaved (if 0) image data. |
1.4.7