Accessing the On-Camera Frame Buffer

Applicable Products

This Application Note applies to Blackfly, Chameleon3, Flea2, Flea3, Grasshopper, Grasshopper2 and Grasshopper3.

For Blackfly S, Firefly, Forge, or Oryx, please see Understanding Buffer Handling.

Overview

The purpose of this Technical Application Note is to describe how users can directly interact with the on-board frame buffer of a supported camera through the registry. 

The frame buffer has been shown to be useful in a number of different scenarios.  Most of these scenarios fall into one of two categories:

• Cases where retransmission of an image is required due to data loss or corruption
• Multiple camera configurations where there is not enough bandwidth to capture sequences in the desired configuration.

The Grasshopper, Grasshopper2, Flea2 FL2G-13S2, Flea2 FL2G-50S5 and Flea3 have 32 MB of memory that can be used for temporary image storage.

Please refer to the Digital Camera Register Reference for more details on accessing and the format of any registers referred to in this document.

Register Description

IMAGE_RETRANSMIT: 12E8h
This register provides the user with an interface to the camera’s frame buffer functionality.

Format:

Using the Frame Buffer

All images pass through the frame buffer mechanism.  This introduces relatively little delay in the system because of the fact that the camera does not wait for a full image to arrive in the buffer before starting transmission over the 1394 interface but rather lags only a few lines behind.

The user can cause images to accumulate in the frame buffer by enabling the HoldImg bit of register 12E8h.  This effectively disables the transmission of images over the 1394 interface in favor of accumulating them in the frame buffer.  The user is then required to use the remaining elements of the interface to cause the transmission of the images.

The buffer system is circular in nature, storing only the last 32MB worth of image data.  The number of images that this amounts to depends on the currently configured image size.

The standard user interaction involves the following steps:

• Configure the imaging mode.

This first step involves configuring the format, mode and frame rate in which the camera will acquire images.  This can be done by either directly manipulating the DCAM registers or using the higher level functionality associated with the software library being used.  Depending on the software package, this may involve going so far as to configure the camera, perform bandwidth negotiation and grab an image.  In cases where bandwidth is restricted, the user will want to disable transmission and free the bandwidth after the camera is configured.

• Enable frame buffer accumulation

The second step involves enabling the HoldImg bit of register 12E8h.  Enabling this bit results in images being accumulated in the frame buffer rather than immediately being transmitted out over the 1394 interface.

• Negotiate bandwidth with the camera

Having accumulated some number of images on the camera, bandwidth will have to be renegotiated if it has not been done already.  In most cases, this will involve effectively starting the camera in the imaging mode configured in step (1).

• Transmit images off of the camera.

The final step involves poking bits [24-31] of register 12E8h in order to cause the camera to transmit images from the frame buffer over the 1394 interface.  Every write to the register will cause a single image to be transmitted. 

A couple of items to note are:

• Although it is possible to repeatedly transmit the same image, there is no way to access images that are older than the last image transmitted. 
• Whether by enabling trigger or disabling isochronous data, switching out of a free running mode will leave the last image transmitted in an undefined state.
• The frame buffer is volatile memory that is erased after power cycling. If you want to store images on the camera after power cycling, use flash memory. Accessing flash memory is significantly slower than accessing the frame buffer, and storage is limited. To determine if your camera supports flash memory, and the amount of storage available, consult your camera’s technical reference manual, or query the DATA_FLASH_CTRL register 1240h, described in the Point Grey Digital Camera Register Reference. For example code, refer to the SaveImageToFlashEx example program, included with the FlyCapture SDK.

There are two basic scenarios in which a customer may want to use the frame buffer system.  These scenarios are outlined below.

Retransmitting an Image in External Trigger Mode

There are occasions where it might be beneficial to retransmit an image when in an external trigger mode.  Having configured the camera to be running in an external trigger mode, the user can cause the camera to retransmit an image by doing the following:

• Read the current state of the IMAGE_RETRANSMIT register 12E8h: 

Reading register 12E8h indicates that the camera supports the frame buffer mechanism, the feature is currently disabled and in the current imaging mode, the system is capable of storing up to 7 images.

• Enable image hold: 

Setting bit 6 of register 12E8 enables access to the frame buffer.

• Retransmit the last image:

Writing a value of 00 to bits 24-31 will cause the last image to be retransmitted.

• Disable the hold image bit to return to normal operation

Writing a 0 to bit 6 of register 12E8 disables access to the frame buffer and returns the camera to normal operation.

Storing images for later transmission

A second scenario where this functionality is useful involves the storage of images for transmission at a later time.  In this case, having configured the camera to be running in the desired imaging mode, enabling the hold image bit will stop images from being transmitted out over the 1394 interface in favor of accumulating in the frame buffer.  Again, assuming the camera is configured to run in an external trigger mode:

• Read the current state of register 12E8h:

Again, this value indicates that the camera supports the frame buffer mechanism, the feature is currently disabled and in the current imaging mode, the system is capable of storing up to 7 images.

• Enable hold image mode:

Setting bit 6 of 12E8h enables hold image mode, resulting in images being accumulated in the frame buffer rather than being immediately transmitted.

• Aquire 4 images:

Writing the software trigger register 4 times results in 4 images being accumulated in the frame buffer.  The last 8 bits of 12E8h will now indicate that there are 4 images in the frame buffer.

• Transmit two images:

Writing 01 to bits 24-31 of 12E8h results in a single image being transmitted and the number of images available being decremented by one.  After transmitting two images, a subsequent read of the register indicates that there are two images left.

• Skip one image and transmit the next image:

Writing 02 to bits 24-31 of 12E8h causes the camera to skip one image and transmit the second image from the buffer.  A subsequent read of the register indicates that there are no un-transmitted images left in the buffer.

• Retransmit the last image:

Finally, writing 00 to bits [24-31] of 12E8h causes the retransmission of the last image.