EDT Digital Imaging Library

Collaboration diagram for EDT Digital Imaging Library:

Modules
	Startup / Shutdown
	Settings
	Initialization
	Acquisition
	Communications/Control
	Utility
	Debug

Detailed Description

The PDV digital imaging library (pdvlib) provides a C language interface to the PDV device driver, including routines for image capture, save, and device control.

The library is designed for use with all EDT Digital Imaging boards, including the VisionLink series, PCIe and PCI DV, DVa and DV series Camera Link and legacy AIA interfaces, and PMC and Compact PCI variants. The library also has components to support the Camera Link simulator boards including the PCI DV CLS, PCIe8 DV CLS and PCIe8 DVa CLS.

The PDV library sits on top of the lower-level EDT DMA Library (edtlib). Library functions from both libraries operate on the same device handle, and routines from both libraries can be used in the same application. However pdvlib (pdv_) subroutines are designed to handle the extra bookkeeping, error-recovery, triggering and timing functionality that is present on EDT Digital Imaging boards. Therefore direct calls to edtlib (edt_) subroutines should only be made when they provide functionality that is not present in an equivalent or similar pdvlib call. Most notable are the DMA image capture subroutines – pdvlib DMA should always be used (e.g. pdv_multibuf(), pdv_start_images(), pdv_wait_images()), rather than calling the lower-level edtlib DMA subroutines directly (e.g. edt_configure_ring_buffers(), edt_start_buffers(), edt_wait_for_buffers().) However this restriction does not apply to the EDT Message Handler Library.

Note

Applications that access EDT boards must be linked with appropriate library (32 or 64-bit) for the platform in use. Applications linked with 32-bit EDT libraries will not run correctly on 64-bit systems, or vice-versa.

All routines access a specific device whose handle is created and returned by the pdv_open() or pdv_open_channel() routine. PDV applications typically include the following elements:

1. The preprocessor statement:

   #include "edtinc.h"

2. A call to pdv_open() or pdv_open_channel(), such as:

   PdvDev pdv_p = pdv_open_channel(EDT_INTERFACE, 0, 0);

   (EDT_INTERFACE is defined as "pdv" in edtdef.h.)
3. Device control or status calls, such as pdv_get_height(), as in:

   int height = pdv_get_height(pdv_p);

4. Ring buffer initialization code, such as:

   pdv_multibuf(pdv_p, 4) ;

5. Data acquisition calls, such as pdv_image() (which acquires an image and returns a pointer to it), as in:

   unsigned char *image = pdv_image(pdv_p) ;

6. A check for timeouts (to flag a problem in the case of an unplugged camera, misconfiguration, or other reason for data loss), as in:

   int t = pdv_timeouts() ;

   followed by appropriate action if new timeouts are detected, such as error output & timeout recovery code per simple_take.c
7. A call to pdv_close() to close the device before ending the program, as in:

   pdv_close(pdv_p) ;

8. Appropriate settings in your makefile or C workspace to compile and link the library files.
9. On Linux systems, the -lpdv and -ledt option to the compiler, to link the library file libpdv.so with your program.
10. On Linux systems, the -L and -R options to specify where to find the dynamic libraries at link- and runtime respectively. (See the makefile provided for examples.)
11. On Linux systems, the -mt option to the compiler (because the library uses multithreading), and the -lm option to the compiler (because it uses the math library).

To compile the library as a shared (.so) library on Linux, the following steps are necessary:

1. run

   make clean

2. add

   -fPIC

   to the ALL_CFLAGS macro in the makefile
3. switch the library macro in the makefile:

   LIBRARY=$(PDVLIB)

See the makefile and example programs provided in the install directory for examples of compiling code using the digital imaging library routines. Windows packages include a Visual Studio (8) solution and project files in install_dir\projects.vs2008.

Suggested starting points for acquisition are the simple_take.c, simplest_take.c and other simple_*.c example programs. For serial communication, see serial_cmd.c, a command line serial utility. Other simple_*.c example programs are provided to show specialized functionality.

The PdvDev device status structure is defined in the file libpdv.h. It includes the PdvDependent substructure, and other structure elements that describe the state of the board and camera, as initialized by the current camera configuration file (see the Camera Configuration Guide) or modified by any subsequent API setup calls. These structure elements include values for things such as the current pixel re-order or color interpolation method, size and depth of the image, number and size of currently allocated buffers. To ensure compatibility with future versions of the library, programmers should always use the library calls for getting / setting any library values, and refrain from referencing the structure elements directly. Additionally, anything that can be queried via the subroutine calls such as currently set image width, height and depth should be done via subroutine calls rather than hard-coding specific values.

The PDV library source files are included in the installation. Most but not all routines are documented here. Undocumented routines include internals, custom, special purpose and obsoletes. Feel free, however, to look through the library source code and use (with caution) any routines that are appropriate. Email tech@.nosp@m.edt..nosp@m.com if you have questions about specific routines.

Note

When acquiring images in multithreaded applications, all routines that deal with starting, waiting for, or aborting images or buffers should be in the same thread.

Routines are divided into the following modules. You can use the Search button at the top of this page (in the HTML version of this doc) to search for specific library routines.