[ Previous | Next | Contents | Glossary | Home | Search ]
Ultimedia Services Version 2 for AIX: Programmer's Guide and Reference

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:

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:

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

VideoIO Object Methods

VideoIO includes the following methods:

open Opens the video capture/playback device.
close Closes the video capture/playback device.
set_input_image_size Sets the the dimensions of the image coming from the analog device.
get_input_image_size Gets the dimensions of the image.
set_output_image_format Sets the format of the output image.
get_output_image_format Gets the format of the output image.
set_analog_video_format Sets NTSC or PAL as the analog source.
get_analog_video_format Gets the format of the analog source.
set_capture_rate Sets the capture speed rate in frames per second.
get_capture_rate Gets the capture speed rate in frames per second.
set_quality_factor Sets the quality factor of JPEG compression.
get_quality_factor Gets the quality factor of JPEG encoder.
set_compression Starts or stops the compressed capture.
get_compression Returns the compression flag.
set_uncompression Starts or stops the uncompressed capture.
get_uncompression Returns the uncompression flag.
set_analog_video_monitor Starts or stops monitoring video.
get_analog_video_monitor Gets the video out monitoring flag.
set_colormap Sets the colormap of the video device.
get_colormap Gets the colormap of the video device.
get_component_number Gets the component number from the compressed frame data.
set_colormap_index Sets the start entry of colormap.
get_colormap_index Gets the entry of colormap.
set_colormap_size Sets the size of colormap.
get_colormap_size Gets the size of colormap.
set_subimage_size Sets the subframe within an image.
get_subimage_size Gets the subframe within an image.
set_uncompressed_image_size Sets the dimensions of the uncompressed image.
get_uncompressed_image_size Gets the dimensions of the uncompressed image.
set_q_table Sets quantization tables.
get_q_table Gets quantization tables.
set_Huffman_table Sets Huffman tables.
get_Huffman_table Gets Huffman tables.
put_compressed_frame Puts a compressed frame to the video out device.
put_uncompressed_frame Puts an uncompressed frame to the video out device.
get_compressed_frame Captures a compressed frame.
get_uncompressed_frame Captures an uncompressed frame.
get_next_compressed_video_out_buffer Gets the index of the next compressed buffer.
get_next_uncompressed_video_out_buffer Gets the index of the next uncompressed buffer.
set_video_input_connector Sets the video input connector.
get_video_input_connector Gets the video input connector.
put_jpeg_header Sets the JPEG header.
get_jpeg_header_size Gets the size of the JPEG header.
get_jpeg_header Gets the JPEG header.
setup_uncompressed_capture_buffers Sets the area of memory to capture uncompressed video frames.
setup_compressed_capture_buffers Sets the area of memory to capture compressed video frames.
setup_compressed_video_out_buffers Sets the area of memory to video out compressed video frames to video device.
setup_uncompressed_video_out_butters Sets the area of memory to video out uncompressed video frames to video out device.
flush_uncompressed_capture_buffers Discards any captured data in the uncompressed buffers.
flush_uncompressed_video_out_buffers Discards any video out data in the uncompressed buffers.
flush_compressed_capture_buffers Discards any captured data in the compressed buffers.
flush_compressed_video_out_buffers Discards any video out data in the compressed buffers.
get_compressed_output_ready_count Gets the number of compressed frames awaiting output to video out.
get_uncompressed_output_ready_count Gets the number of uncompressed frames awaiting output to video out.

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:

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.


[ Previous | Next | Contents | Glossary | Home | Search ]