1.  XCAP Application Note — PIXCI® EB1tg and EB1miniTg Frame Generators

The PIXCI® EB1tg and EB1miniTg are Camera Link frame generator cards; they output images and video as would a Camera Link camera. In contrast, the PIXCI® EB1 and EB1mini Camera Link frame grabbers capture images and video from a camera.

The PIXCI® EB1tg and EB1miniTg allow configuring the Camera Link resolution, bit depth, color space, and frame rate. They support both free-run and async-reset (also known as trigger or frame-on-demand) modes, and can output static test pattern images, time-varying test pattern images, or user-supplied images and image sequences.

This application note is intended to help the reader understand and utilize the PIXCI® frame generators, Familiarity with the Camera Link protocol and camera terminology such as free-run and async-reset is assumed. Familiarity with PIXCI® frame grabbers is helpful, as the frame generators can be most easily understood by their similarities and differences relative to, the more commonly used, frame grabbers.

The PIXCI® frame grabbers and generators are supported by XCAP (GUI) and XCLIB (SDK/API) software. To the extent possible, generator and grabber cards have identical, or at least analogous, architecture and controls. Much of the XCAP (GUI) software is identical, or at least symmetric, for grabbers and generators, except for exchange of terminology. The XCLIB (SDK/API) is also identical, except for re-interpreting ‘capture’ and ‘snap’ function names as ‘stream’ and ‘flash’, respectively.

Both frame grabbers and generators use a fixed set of frame buffers in the host computer’s memory for storage of image data,[1] with the direction of pixel data flow and of Camera Link control signals reversed.

Camera Link Video Signals

The PIXCI® frame grabber and generator card’s image resolution, bit depth, number of taps, can be configured. The grabber cards ‘lock’ to the Camera Link clock provide by the camera and accept pixel data at that rate; the generator cards allow selecting the Camera Link clock frequency and rate of pixel data. The grabber cards expect FVAL, LVAL, DVAL (optional) Camera Link signals from the camera, the generator cards output FVAL, LVAL and DVAL (optional) signals. In async-reset mode, the grabber cards assert CC1 to trigger the camera (driven by an external signal applied to the frame grabber, or driven by a button click (GUI) or function call (SDK)); the generator cards accept a signal on CC1 to trigger output of an image (in async-reset mode), or can be triggered via button click (GUI) or function call (SDK).

Free-Run Mode Capture/Stream

In free-run mode, the grabber cards continuously monitor video timing and count FVAL’s. If a frame capture is requested, the pixel data is stored in a designated frame buffer or a specified sequence of frame buffers; otherwise the pixel data is ignored.

In free-run mode, the generator cards maintain continuous, periodic, video timing (i.e. FVAL’s and LVAL’s) and count FVAL’s; the contents of a specified frame buffer, or the contents of a specified sequence of frame buffers, are output as pixel data. If a frame buffer isn’t specified, the generator cards output pixel data of a preselected test pattern; one such test ‘pattern’ is all zeros, and thus black.[2]

A frame grabber ‘snap’ captures one image into the designated frame buffer. In free-run mode, the frame grabber waits for the camera’s next top of frame and captures the following frame. For the frame generator the corresponding activity is ‘flash’; the frame generator waits for the next top of frame (as determined by the card’s internal, periodic timing), and then outputs the contents of the designated frame buffer during the following frame period.

A frame grabber in ‘live’ mode continuously captures incoming frames into one, or perhaps an alternating pair of, frame buffers. A frame generator in ‘live’ mode continuously outputs images from one, or perhaps an alternating pair of, frame buffers.

A frame grabber, using the ‘Video to Frame Buffers’ feature can ‘record’ a sequence of incoming frames by capturing into a sequence of frame buffers; an option allows continuous recording by treating the frame buffers as a circular queue. A frame generator, using the ‘Video from Frame Buffers’ feature can ‘stream’ a sequence of output frames by outputting the contents of a sequence of frame buffers; an option allows continuous streaming by treating the frame buffers as a circular queue.

The XCAP (GUI) application was originally designed for frame grabbers; many of its features may not be useful for frame generator cards. The most important features for use of generator cards, the:

    Stream & Adjust dialog
    Video from Frame Buffers

are analogous to the:

    Capture & Adjust Dialog
    Video to Frame Buffers

features for frame grabbers, but ‘re-tuned’ for use with frame generators. Features such as:

    Save Image
    Load Image
    Save Image Sequence
    Load Image Sequence

do not reference either capturing or streaming, as these features operate upon the contents of frame buffers independent of how frame buffer was, or will be, used. Other features of XCAP may not apply to frame generators, or may show the Snap, Capture, and Record terminology instead of Flash, Stream, and Stream, respectively.

The XCLIB (SDK/API) function names and documentation have not been changed for use with frame generators. The following examples illustrate use of XCLIB with frame grabbers, and the corresponding use with frame generators.

Capture one image and save:

    pxd_doSnap(...)
    pxd_saveTiff(...)

versus load one image and flash:

    pxd_loadTiff(...)
    pxd_doSnap(...)

Continuous capture with eventual save:

    pxd_goLive(...)
    ... until ? ...
    pxd_goUnLive(...)
    pxd_saveTiff(...)

versus load image and continuous stream:

    pxd_loadTiff
    pxd_goLive()
    ... until ? ...
    pxd_goUnLive(...)

Continuous capture into an alternating pair of buffers with eventual save of images:

    pxd_goLivePair(..., 1, 2)
    ... until ? ...
    pxd_goUnLive(...)
    pxd_saveTiff(..., 1, ...)
    pxd_saveTiff(..., 2, ...)

versus load images and continuous stream from an alternating pair of buffers:

    pxd_loadTiff(..., 1, ...)
    pxd_loadTiff(..., 2, ...)
    pxd_goLivePair(..., 1, 2)
    ... until ? ...
    pxd_goUnLive(...)

Sequence capture and save:

    pxd_goLiveSeq(...)
    for (i = 0; i < pxd_imageZdim(); i++)
        pxd_saveTiff(..., i, ...)

versus load sequence and stream:

    for (i = 0; i < pxd_imageZdim(); i++)
        pxd_loadTiff(..., i, ...)
    pxd_goLiveSeq(...)

The example code above uses pxd_loadTiff() and pxd_saveTiff(). The same code logic applies if they are replaced by pxd_writeushort and pxd_readushort, or pxd_writeuchar and pxd_readuchar, to modify the contents of a frame buffer or to copy the contents of a frame buffer.

Video to/from Disk

The frame buffers are simply shared memory; shared between the video DMA engine and the application. The application can read the contents of a frame buffer while capture is in progress, or write the contents of a frame buffer while streaming is in progress. If using single buffer capture/stream (with pxd_goLive()), the application will likely read a partially updated image, or cause the streaming of a partially updated image (with exceptions for very slow video and/or very fast computers). Double buffering via pxd_goLivePair(), or N−buffering via pxd_goLiveSeq() in continuous/circular mode, supports applications such as continuous video to disk, or continuous video stream from disk, without the risk of ‘partial’ artifacts.

Functions such as pxd_capturedBuffer, pxd_capturedFieldCount, and pxd_buffersFieldCount, can be used to monitor the progress of pxd_goLiveSeq(). For a frame grabber, they report the last frame buffer that was (completely) captured, the FVAL count at the time the last frame buffer was captured, or the FVAL count when a specified frame buffer was captured and help determine when the contents of one or more frame buffer should be saved and thus ‘emptied’. For a frame generator, they report the last frame buffer that was (completely) streamed, the FVAL count at the time the last frame buffer was streamed, or the FVAL count when a specified frame buffer was streamed and help determine when the contents of one or more frame buffers are ‘empty’ and should be loaded.

Async-Reset Mode Capture/Stream

In async-reset mode, the grabber cards continuously monitor video timing and count FVAL’s. If a frame capture is requested, the pixel data of a video frame is stored in a designated frame buffer; otherwise the pixel data is ignored. This is, in fact, identical to their behavior in free-run mode; the grabber card’s participation in triggering the camera is independent of of the capture process.

In async-reset mode, the generator cards output one video frame (i.e. FVAL and LVAL’s) per trigger, neither FVAL, LVAL, DVAL nor image data are output while awaiting a trigger. As for free-run mode, the cards output the contents of a specified frame buffer as pixel data, or outputs pixel data of a preselected test pattern if no frame buffer is specified.

For frame grabbers, a ‘snap’ must be used to ‘arm’ the frame grabber to capture the next frame from the camera. In a button-click trigger mode, the ‘snap’ also triggers the camera via CC1 prior to arming the frame grabber.

For frame generators, a ‘flash’ must be used to arm the frame generator so as to output desired pixel data upon sensing a trigger via CC1; if not armed, a preselected test pattern is output upon sensing a trigger. In a button-click trigger mode, the ‘flash’ also triggers the frame generator to output an image.

Some cameras support triggering via a serial command. Such a feature has no impact on the video, image, or trigger operation of a frame grabber. For frame generators simulating such a camera, the application can implement this behavior by reading serial commands, and then invoking pxd_doSnap() in button-click trigger mode.

The same XCLIB code is used to ‘snap’ or ‘flash’ in async-reset mode as in free-run mode (above) using pxd_doSnap().

Serial Communication

Both frame grabbers and frame generator cards support serial communication via Camera Link. All Camera Link standard baud rates, 8 bit data, and full duplex communication, are supported.

While the frame generator cards are intended to simulate a camera, they do not, themselves, implement a suite of serial commands; nor do they send a serial ‘hello’ message on start-up.[3] The XCAP (GUI) PIXCI® Serial Terminal allows the user to type and view serial data. The XCLIB (SDK/API) pxd_serial*() functions allow explicit reading and writing of serial data; implementation of a suite of serial commands is up to the application programmer.

As for the frame grabbers, the serial communication of frame generators can be also accessed via the Camera Link Serial API (i.e. clserEPX.DLL, Windows), a virtual COM port (Windows), or a virtual tty (Linux).

General Purpose Inputs/Outputs

Both frame grabbers and frame generators support one or two General Purpose Input signals and one or two General Purpose Output signals. These level sensitive signals allow the XCAP (GUI) user or the XCLIB (SDK/API) application to sense or control a few external signals and devices without the need of using a separate ‘Parallel I/O’ interface card. A few optional capture/stream features incorporate use of these signals (at the driver level), but, generally, these signals are independent of the triggering and capture/stream process.

In addition to the ‘normal’ General Purpose Input signals, the frame generators report the state of CC1, CC2, CC3, and CC4 signals as additional general purpose, level sensitive, inputs. This is true regardless of whether a CC1, CC2, CC3, or CC4 signal is being used as a trigger input.

For a frame generator with two General Purpose Input signals: bits 0 and 1 of the return value of pxd_getGPIn() are the current values of the General Purpose Input signals, while bits 2 thru 5 are the current values of the CC1 thru CC4 signals, respectively.

Trigger Inputs

Both frame grabbers and frame generators support a trigger input.

For frame grabbers, in async-reset modes, this trigger input may (depending on configuration) assert CC1 and trigger the camera. Otherwise, transitions (rising or falling, as configured) are counted and available to the XCAP (GUI) user or the XCLIB (SDK/API) application.

For frame generators, in async-reset modes, any one of the trigger input, CC1, CC2, CC3, or CC4 can be used to trigger the output of one image. (For the sake of brevity, these alternatives to CC1 triggers were not mentioned previously).

Independent of free-run vs async-reset modes, any transitions on one of the trigger input, CC1, CC2, CC3, or CC4 can be counted and available to the XCAP (GUI) user or the XCLIB (SDK/API) application.

Miscellaneous Topics

For frame grabbers, the XCAP (GUI) image viewer window displays a selected frame buffer (or displays a sequence of the frame buffers, or a displays an array of tiles with all frame buffers, etc.); the image viewer window is updated when the a new image has been captured into a frame buffer. For frame generators, the image viewer window also displays a selected frame buffer (or variations thereof), but whether or not the contents of a frame buffer was streamed has no effect on the image display.

The contents of the current (or any) frame buffer is not changed by the frame generator’s output of the preselected test pattern data. The image viewer window will not display the preselected test pattern data; nor will Histogram, Pixel Plot or similar features reflect the preselected test pattern data.

The pxd_doSnap function is mentioned above for capturing or generating one image, possibly with a side effect of triggering the camera or triggering the generator card. The pxd_doSnap waits until the operation is complete, a parameter specifies the allowable wait duration before timeout. For the sake of brevity, the alternate pxd_goSnap was not mentioned previously. The pxd_goSnap, initiates capture or generation of an image with optional triggering and returns (almost) immediately; the application can poll to detect completion or await an Event (Windows) or signal (Linux). The pxd_doSnap is essentially a convenience; a pxd_goSnap followed by a wait for completion.

Just as XCAP’s

    Capture & Adjust Dialog

provides adjustments for PIXCI® frame grabbers, XCAP’s

    Stream & Adjust Dialog

provides PIXCI® frame generators a simple GUI for adjusting the resolution, bit depth, number of taps, and free-run versus async-reset modes. After setting and testing the configuration, export the video setup for use by XCLIB. See XCLIB’s Using a Video Format Configuration Exported by XCAP application note.

For frame grabbers, the optional ‘Multi-Tap Corrections’ allow reordering captured pixel data, so as to correct for cameras that don’t output pixels in the typical left-to-right and top-to-bottom order. For frame generators, for user supplied pixel data, the ‘Multi-Tap Corrections’ applies the inverse ordering correction - allowing simulation of a camera’s atypical data ordering without pre-processing of the pixel data. The frame generator’s preselected test pattern data is not affected by the ‘Multi-Tap Corrections’.

After changing the video resolution, bit depth, color space, bit-packing, or multi-tap corrections parameters, any old user supplied data in the frame buffer(s), viewed under the new parameters, will typically appear garbled. Or the frame buffer(s) will be zero’ed, if the ‘Clear Frame Buffers in Format Change’ option is set (i.e. via XCAP’s Driver Assistant - Advanced Options or XCLIB’s ‘Driver Configuration Parameters’). For PIXCI® frame grabbers, new image(s) should be captured to replace old data. For PIXCI® frame generators, the frame buffer(s) should be reloaded or rewritten after changing the video parameters (this does not apply to preselected test pattern data, which is generated on-the-fly as per the current video parameters).

The Video for Linux (V4L2), Frame Server (DirectShow), TWAIN, and ImagePro drivers — providing alternate methods of accessing PIXCI® frame grabbers — do not support the PIXCI® EB1tg or EB1miniTg frame generator cards.

For PIXCI® frame grabbers, XCAP’s Capture & Adjust dialog is typically constructed so that its right side has camera configuration controls (typically via serial commands), while the left side has PIXCI® configuration controls along with XCAP options and features. For PIXCI® frame generators, XCAP’s Stream & Adjust dialog is organized with the right side providing controls of the ‘phantom’ camera represented by the frame generator card, while the left side has controls for other features of the frame generator card (i.e. features not typically associated with a camera) along with XCAP options and features.

For generator cards configured in free-run mode, the reported video rate will be non-zero and the field count will continuously increase regardless of whether Flash or Live is selected. The field count and frame rate reflect continuous, periodic, video timing; which is maintained when outputting the preselected test pattern.

For frame grabbers, the ‘PCI FIFO Overflow’ fault message indicates that data could not be pushed through the PCI or PCIe bus at video rates. For frame generators, the same fault message indicates that data could not be pulled through the PCIe bus at video rates; an underflow condition. In either case, resolution of the problem requires adjustments via the PC’s BIOS; configuring video for lower resolution, smaller bit depth, fewer taps, or reduced clock rate; or selecting a different PC. See the PC Configuration Tips application note.

Copyright (C) EPIX, Inc. All Rights Reserved

Updated: 27 March 2023

Footnotes __________

1. The number of frame buffers can be changed, typically by modifying
driver’s boot parameters and rebooting. The number of frame buffers
is ‘fixed’ in that the number doesn’t change as images are streamed or
captured.

2. Interpretation as black assumes a monochrome, RGB, or Bayer interpre-
tation of the pixel data.

3. Support of a suite of serial commands and/or serial messages is al-
lowed by the Camera Link specification, but not required. The Camera
Link specification does not specify or suggest message formats.