Programming with the VideoIO Object

In Ultimedia Services, the VideoIO object programming interface to the Ultimedia Services Video I/O Adapter provides the following functions:

• Capture of compressed JPEG images from an analog video source.
• Capture of uncompressed images from an analog video source.
• Output of compressed JPEG images to an external analog video device, such as a VCR or monitor. Upon receipt of the JPEG compressed frames, the Ultimedia Services Video I/O Adapter decompresses and encodes each image.
• Output of uncompressed images to an external analog video device, such as a VCR or monitor. The data must be in 640x480 YUV422 format.

To use this object, an application first calls methods to create and initialize the object. After setting up the ring buffer data structure, it supplies the object with index to the input/output data of the ring buffer, and calls a method to capture/playback the compressed or uncompressed frame.

To learn more about the VideoIO object, see:

• VideoIO Object Methods
• Using Ring Buffers
• Capturing Uncompressed Images
• Capturing Compressed Images
• Outputting Compressed Images to Analog Video Out
• Outputting Uncompressed Images to Analog Video Out
• Concurrent Capture of Uncompressed Images and Compressed Images
• VideoIO Performance Factors
• Connectors

For introductory information, see Programming with Movie Capture and VideoIO Objects.

VideoIO Object Methods

VideoIO includes the following methods:

Using Ring Buffers

typedef struct

{
unsigned long _maximum;
unsigned long _length;
        // The number of elements. Must be greater than or
        equal to 2

UMSVideoIO_RingBufferElement *_buffer;
        // The pointer to the array of RingBufferElement
        structures 
} _IDL_SEQUENCE_UMSVideoIO_RingBufferElement;

struct RingBufferElement

{
long Address;            // Pointer to the start of the buffer
long AfterHeader;        // Pointer to the image data

Using AfterHeader and Address

When uncompressed data is in the buffer, Address and AfterHeader should be equal. When compressed data is in the compressed video out buffer, Address points to the start of the block of data. If the block of data does not have a JPEG header, AfterHeader should be equal to the Address. If the block of data does have a header, AfterHeader points to the data after the header.

The Ultimedia Services Video I/O Adapter does not process the header. For compressed capture, the data does not have a header and Address and AfterHeader should be equal.

long    SizeOfBuffer;    //maximum data length
long    SizeOfDataInBuffer;
                         //length of data in the buffer
long    InUseByCaller;   //This field is updated by Device
                         //Driver indicating when the buffer is
                         //available. Is reset by the application
                         //when finished with the data.
long    NumberOfOverruns;//This fields indicates number
                         //of frames lost
};    

To set up the ring buffers for data transfer, do the following:

1. Allocate the ring buffer sequence structure.
2. Set the number of elements in sequence structure to a value greater than or equal to 2. This corresponds to the number of RingBufferElement structures in the ring buffer. This value should be enough to account for the expected latencies in processing the buffers.
3. Allocate the array of the ring buffer data structures.
4. The array of the structures describing the buffers and the buffers themselves must not share the same pages of memory. No single page can be used for more than one buffer. The page size is 4KB.

An example of how to set up the ring buffer structure and array follows:

_IDL_SEQUENCE_UMSVideoIO_RingBufferElement *ring_buffer;
UMSVideoIO_RingBufferElement *rbuffer1;
long  each_buffer_size;
long  number_of_elements;

each_buffer_size = width * height * pixel_size;
number_of_elements = 4;
 

ring_buffer = (_IDL_SEQUENCE_UMSVideoIO_RingBufferElement*) malloc(sizeof(_IDL_SEQUENCE_UMSVideoIO_RingBufferElement));

if (ring_buffer <= 0 )
{
printf("Cannot malloc ring_buffer\n");
fflush(stdout);
exit(0);

}
ring_buffer->_length = number_of_elements;
ring_buffer->_maximum = number_of_elements;

ring_buffer->_buffer = (struct UMSVideoIO_RingBufferElement *)
malloc(sizeof(struct UMSVideoIO_RingBufferElement) 
        * number_of_elements + 4096);

if (ring_buffer->_buffer <= 0 )
{
printf("Cannot malloc ring_buffer->_buffer\n");
fflush(stdout);
exit(0);
}

rbuffer1 = ring_buffer->_buffer;
for (i=0; i< number_of_elements; i++)
{
rbuffer1->Address = (char *)malloc(each_buffer_size+4*1024);
if (rbuffer1->Address <=0 )
{
printf("Cannot malloc ring_buffer %d\n", i);
fflush(stdout);
exit(0);
}
rbuffer1->Address = rbuffer1->Address + 4096 - (rbuffer1->Address          % 4096);
rbuffer1->AfterHeader = rbuffer1->Address ;
rbuffer1->SizeOfBuffer = each_buffer_size ;
rbuffer1->SizeOfDataInBuffer = 0 ;
rbuffer1->InUseByCaller = 0 ;
rbuffer1++;
} 

Capturing Uncompressed Images

1. Call set_output_image_format to set up the pixel format.
2. Call set_uncompressed_image_size to set up the image size.
3. Allocate the ring buffers.
4. Call setup_uncompressed_capture_buffers to let the device driver pin the buffers and data structures for capturing uncompressed video images. The image data is transferred through DMA operations.
5. Call set_uncompression with an ON value. This starts data transfer into the ring buffers.
6. Call get_uncompressed_frame to get the index into the ring buffer array of the next uncompressed data buffer. The operation can block until the next frame is available.
7. The uncompressed image is now available for use.
8. Set InUseByCaller field to 0 when caller is finished using the data.
9. Go back to step 6 and repeat as many times as needed.
10. Call set_uncompression with an OFF value to indicate that capture is complete.
11. Application can do a flush_uncompressed_capture_buffers to discard any unneeded frames that remain in the ring buffer.

    Note: Failure to set the InUseByCaller field to 0 indicates that the buffer is no longer in use and can cause the device driver to wait indefinitely for a free buffer.

Capturing Compressed Images

1. Call set_analog_video_format to set up select NTSC or PAL.
2. Call set_input_image_size to set up the image size.
3. Allocate the ring buffers.
4. Call setup_compressed_capture_buffers to let the device driver pin the buffers and data structures for capturing compressed video images. The image data is transferred through DMA operations.
5. Call set_compression with an ON value. This starts data transfer into the ring buffers.
6. Call get_jpeg_header_size to get the size of JPEG header and allocate memory for JPEG header.
7. Call get_jpeg_header to get the JPEG header structure.
8. Call get_compressed_frame to get the index into the ring buffer array of the next compressed data buffer. The operation can block until the next frame is available.
9. The compressed image is now available for use.
10. Set InUseByCaller field to 0 when caller is finished using the data.
11. Go back to step 8 and repeat as many times as needed
12. Call set_compression with an OFF value to indicate that capturing is complete.
13. The application can do a flush_compressed_capture_buffers to discard any unneeded frames that remain in the ring buffer.

    Note: Failure to set the InUseByCaller field to 0 indicates that the buffer is no longer in use and can cause the device driver to wait indefinitely for a free buffer.

Outputting Compressed Images to Analog Video Out

1. Call set_analog_video_format to set up format.
2. Call set_input_image_size to set up the image size.
3. Allocate the ring buffers.
4. Call setup_compressed_videoout_buffers to set up ring buffer structure for video out compressed video images.
5. Call put_jpeg_header to set up JPEG header information.
6. Call get_next_compressed_video_out_buffer to get the index of the next compressed data.
7. Store the compressed data in the ring buffer specified by the index.
8. Call put_compressed_frame to let the device driver know that the buffer is filled.
9. Go back to step 6 and repeat as many times as needed.
10. Application can do a flush_compressed_video_out_buffers to discard any unneeded frames that remain in the ring buffer.

    Note: Failure to set the InUseByCaller field to 0 indicates that the buffer is no longer in use and can cause the device driver to wait indefinitely for a free buffer.

Outputting Uncompressed Images to Analog Video Out

1. Call set_analog_video_format to set up format.
2. Call set_uncompressed_image_size to set up the image size.
3. Allocate the ring buffers.
4. Call setup_uncompressed_video_out_buffers to set up ring buffer structure for video out uncompressed video images.
5. Call get_next_uncompressed_video_out_buffer to get the index of the next uncompressed buffer.
6. Fill the buffer with uncompressed video data.
7. Call put_uncompressed_frame to let the device driver know that the buffer is filled.
8. Go back to step 5 and repeat as many times as needed.
9. Application can do a flush_uncompressed_videoout_buffers to discard any unneeded frames that remain in the ring buffer.

   Note: Failure to set the InUseByCaller field to 0 indicates that the buffer is no longer in use and can cause the device driver to wait indefinitely for a free buffer.

Concurrent Capture of Uncompressed Images and Compressed Images

1. Call set_output_image_format to set up the pixel format.
2. Call set_uncompressed_image_size to set up the image size.
3. Allocate the uncompressed capture ring buffers.
4. Call setup_uncompressed_capture_buffers to let the device driver pin the buffers and data structures for capturing uncompressed video images. The image data is transferred through DMA operations.
5. Call set_analog_video_format to set up select NTSC or PAL.
6. Call set_input_image_size to set up the image size.
7. Allocate the compressed capture ring buffers.
8. Call setup_compressed_capture_buffers to let the device driver pin the buffers and data structures for capturing compressed video images. The image data is transferred through DMA operations.
9. Call set_uncompression with an ON value. This starts data transfer into the ring buffers.
10. Call set_compression with an ON value. This starts data transfer into the ring buffers.
11. Call get_jpeg_header_size to get the size of JPEG header and allocate memory for JPEG header.
12. Call get_jpeg_header to get the JPEG header structure.
13. Call get_compressed_frame to get the index into the ring buffer array of the next compressed data. The operation can block until the next frame is available.
14. The compressed image is now available for use.
15. Set InUseByCaller field to 0 when caller is finished using the data.
16. Call get_uncompressed_frame to get the index into the ring buffer array of the next uncompressed data. The operation can block until the next frame is available.
17. The uncompressed image is now available for use.
18. Set InUseByCaller field to 0 when caller is finished using the data.
19. Go back to step 13 and repeat as many times as needed.
20. Call set_compression with an OFF value to indicate that capturing has been completed.
21. Call set_uncompression with an OFF value to indicate that capturing has been completed.
22. If desired, application can do a flush_uncompressed_capture_buffers to discard any unneeded frames that remain in the ring buffer.
23. If desired, application can do a flush_compressed_capture_buffers to discard any unneeded frames that remain in the ring buffer.

    Note: Failure to set the InUseByCaller field to 0 indicates that the buffer is no longer in use and can cause the device driver to wait indefinitely for a free buffer.

VideoIO Performance Factors

The following can influence how well the VideoIO adapter captures or plays back the video frames:

• Number of frames per second
• Image size
• Image output format
• Number of buffer elements

Connectors

The set_video_input_connector method allows choices of either S-Video input or Composite Video Baseband Signal input. Only one connection can be active during a session. Refer to the Ultimedia Services Video I/O adapter hardware documentation for information on your video input jacks.

For introductory information, see Programming with Movie Capture and VideoIO Objects.