The simplest way to acquire an image from an EDT digital video 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: 8 extdepth: 24 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: 10, 12, 14 or 16 extdepth: 24 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: 8 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 board must be flashed with medium mode FPGA such as pdvcamlk_pir.bit) | 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) |
| Flushes the board's input FIFOs, to allow new data transfers to start from a known state. | |
| 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. | |
| 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) |
| Triggers the camera and reads image data from the PCI DV. | |
| 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, an alternative to pdv_multibuf which allocates the buffers internally. | |
| 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) |
| Gets the number of times the PCI DV 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 without conversion. | |
| 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.
| 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 |
| 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.
(see pdv_image, pdv_start_image, pdv_wait_image) This routine is similar to pdv_set_buffers except that it allocates the buffers itself.
Additional buffers speed acquisition and display. The number of buffers is limited only by the amount of host memory available; however, 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.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| numbufs | The number of buffers to allocate. Must be 1 or greater. Four is recommended for typical applications. |
| int pdv_overrun | ( | PdvDev * | pdv_p | ) |
| int pdv_read | ( | PdvDev * | pdv_p, | |
| unsigned char * | buf, | |||
| unsigned long | size | |||
| ) |
Triggers the camera and reads image data from the PCI DV.
This is the lowest-level method for aquiring an image; however, for best performance, use ring buffer calls such as pdv_multibuf or pdv_start_image. Never use this routine when ring buffering is in effect (after calling pdv_multibuf), or mix it 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_width(pdv_p) * pdv_get_height(pdv_p) * bits2bytes(pdv_get_depth(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, an alternative to pdv_multibuf which allocates the buffers internally.
(see pdv_image, pdv_start_image, pdv_wait_image)
This function takes an argument that is an array of buffers allocated by the user. Otherwise, this routine is similar to 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 PCI DV C-Link and PCI DV FOX.
| 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 | ) |
Gets the number of times the PCI DV 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.
A robust application will check this after every aquire. If broken images, slow frame rates or blank images are encountered, it will usually be associated with an image timeout.
Timeouts caused by bandwidth saturation often result from installing a fast EDT board such as the PCI DV C-Link in a standard 33Mhz PCI slot which will cut the board's maximum transfer speed in half, or installing multiple high-bandwidth boards (EDT or other) on the same PCI bus. For more information on bandwidth requirements see EDT's System Requirements web page.
| pdv_p | pointer to pdv device structure returned by pdv_open |
int t, total_timeouts = 0; t = pdv_timeouts(pdv_p); if (t > total_timeouts) { printf("got timeout\n"); total_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 without conversion.
| 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.
| 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 %s\n", edt_timestamp(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.
| 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 %s\n", edt_timestamp(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.
| 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.
| 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: %s\n", edt_timestamp(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.
| 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.
| 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.
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.
| 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.5.1