UMSVideoIO provides methods to open, close, and access the Ultimedia Video I/O adapter. The UMSVideoIO object is not a generic class to access any video device driver. It provides methods to capture compressed JPEG frames and to capture uncompressed frames with YUV422, RGB8, and RGB24 format. It can also provide methods to output the compressed JPEG frames and the uncompressed frames with YUV422 format to analog video output.
To learn more about the UMSVideoIO object, see:
For introductory information, see Movie Capture and Playback Objects.
enum ReturnCode {
Success,
Failure,
UnsupportedFormat,
InvalidSubimage,
InvalidImageSize,
Uninitialized,
InvalidQualityFactor,
InvalidTableID,
OutOfRange,
NotAvail,
NoDevice,
NotOpen,
ValueChanged,
NoBuffer,
NullPointer,
WrongIndex,
BufferNotAvailable
};
enum OnOff {
Off,
On
};
enum JPEGHeaderFlag {
NoDQT_DHT,
WithDQT,
WithDHT,
WithDQTandDHT
};
struct RingBufferElement {
long Address,
longAfterHeader
long SizeOfBuffer,
long SizeOfDataInBuffer,
long InUseByCaller,
long NumberOfOverruns,
};
When uncompressed data is in the buffer, then Address and AfterHeader should be equal. When compressed data is in the buffer, then Address points to the start of the block of data. If the block of data does not have a JPEG header, then AfterHeader should be equal to the Address. If the block of data does have a header, then 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.
This object defines the following string definitions in the UMSStrings.h file in /usr/lpp/UMS6000/include:
#define NTSC "NTSC" #define PAL "PAL" #define YUV422 "YUV422" #define RGB8Dither "RGB8Dither" #define RGB24 "RGB24" #define QTABLE_A_Y "QTABLE_A_Y" #define QTABLE_A_C "QTABLE_A_C" #define QTABLE_B_Y "QTABLE_B_Y" #define QTABLE_B_C "QTABLE_B_C" #define HUFFMANYDC "HUFFMANYDC" #define HUFFMANYAC "HUFFMANYAC" #define HUFFMANCDC "HUFFMANCDC" #define HUFFMANCAC "HUFFMANCAC" #define INPUT_COMPOSITE "INPUT_COMPOSITE" #define INPUT_SVIDEO "INPUT_SVIDEO"
This method opens the specified video device. If there is an error this method returns Failure code.
| in string path | The name of a video device to be opened. |
This method closes the video device. If the device is not open or the close command fails then NotOpen or Failure is returned.
This method sets the dimensions of the image coming from the analog source. This applies to both uncompressed images and compressed images. The valid sizes are format specific.
This method returns Success if width and height are valid. Otherwise, the closest valid width and height is set, and ValueChanged is returned.
For NTSC the valid image sizes are 640x240 and 320x240. For PAL the valid image sizes is 768x288 and 384x288. The default image size is 640x240.
| inout long width | Specifies the width of the input image. |
| inout long height | Specifies the height of the input image. |
This function allows the application to query the dimensions of the image size. This applies to both compressed and uncompressed images. The valid sizes are format specific.
| inout long width | The current setting of the width of image size is returned. |
| inout long height | The current setting of the height of image size is returned. |
This function sets the format of the output image data to be created by the video device. This method is used for uncompressed images. If the format is unsupported an error code UnsupportedFormat is returned. If any other error happens an error code Failure is returned. The default format is YUV422.
| in string format | The string specifies the desired format. Possible values of the format are YUV422, RGB8Dither, and RGB24. |
This function allows the application to query the output image format for uncompressed images.
| out string format | A string containing the current image format is returned. The possible values of the format are YUV422, RGB8Dither, and RGB24. |
This function sets the video format. The output and input video formats are the same for NTSC and PAL. The default video format is NTSC.
If the format is unsupported, an error code UnsupportedFormat is returned. If any other error happens, an error code Failure is returned.
| in string format | The string specifies the video format. The possible values of the format are NTSC and PAL. |
This function allows the application to query the video format.
| out string format | A string containing the video format is returned. The possible values of the format are NTSC and PAL. |
This function allows the application to set the capture rate. This method returns Success if the rate is valid. Otherwise, the closest valid rate is set, and ValueChanged is returned.
| inout double rate | Specifies number of frames per second to capture video. |
This function allows the application to query the capture rate.
| inout double rate | The capture rate (the number of frames per second) is returned. |
The quality factor lets you trade off compressed file size against quality of the reconstructed image. The higher the factor setting, the larger the JPEG file, and better quality it is. The range of the factor is between [1-100]. The default quality factor is 80.
This method returns Success if the factor is valid. Otherwise, the closest valid factor is set, and ValueChanged is returned.
| inout long factor | Specifies quality factor of JPEG compression. |
This function allows the application to query the quality factor of the encoder.
| inout long factor | The return value is the current quality factor setting. The value is between [1-100]. |
This function allows the application to set the compression flag. When the flag is set On, the video device is ready for compress image. The setup_compressed_capture_buffers method must be issued before this call.
| in OnOff flag | The flag to set compression. |
| NoBuffer | Application must do a setup_compressed_capture_buffers before calling this method. |
This method allows the application to query the compression flag.
| inout OnOff flag | Reports whether capturing of compressed images is turned on. The possible Return Values are On and Off. |
This function allows the application to set the uncompression flag. When the flag is set On, the video device is ready for uncompressed images. setup_uncompressed_capture_buffer method must be issued prior to this call.
| in OnOff flag | The flag to set uncompression. |
| NoBuffer | Application must do a setup_uncompressed_capture_buffers before calling this method. |
This method allows the application to query the uncompression flag.
| inout OnOff flag | Reports whether capturing of uncompressed images is on. The possible Return Values are On and Off. |
This function allows the application to turn the analog video monitoring on or off. When the flag is set On, the video device begins monitoring. By default this is turned On.
This flag is turned Off during playback to video out.
| in OnOff flag | The flag to set video out monitor. |
This method allows the application to query the analog video monitor flag.
| inout OnOff flag | The possible Return Values are On and Off. |
This function allows the application to set the color map of the uncompressed data returned from the video device. Not setting a colormap results in 3:3:2 RGB data being returned. Mapping is done in the VideoIO object, not in the hardware.
The colormap is used only if the output image format is RGB8Dither.
This function allows the application to query the color map being used by the VideoIO object to map the uncompressed data received from the video device.
This function gets the component number from the compressed image. For color images, component_number is equal to 3, and for mono images and Y only images, component_number is equal to 1. If comp_image is equal to NULL, the component_number corresponds to a compressed image captured from the video device.
| in sequence <octet> comp_image | Pointer to the start of the compressed JPEG image header. |
| inout long component_number | Number of components in the frame is returned. |
This method sets up the color map table characteristics of the VideoIO object. The default base_index is 128.
This method returns Success if the base_index is valid. Otherwise, the closest valid base_index is set, and ValueChanged is returned.
The colormap is used only if the output image format is RGB8Dither.
| inout long base_index | Sets the base address of the uncompressed image's color map. |
This method gets the base index for the color lookup table used by the VideoIO object to map the image frame.
| inout long base_index | The base address of the uncompressed image's color map. |
This method sets up the color map table size of the VideoIO object. The default size is 128.
This method returns Success if the size is valid. Otherwise, the closest valid size is set, and ValueChanged is returned. The colormap is used only if the output image format is RGB8Dither.
| inout long size | The number of color table entries that should be used by the VideoIO object. |
This method gets the colormap size for the color lookup table used by the UMSVideoIO object to map the image frame.
| inout long size | The length of the color map is returned. |
This function allows a sub-frame within an image to be compressed. This function does not need to be called if the full image is to be encoded. The offsets must be positive integer and even values. The set_input_image_size function must also be called to specify the actual input image size.
The default subimage size is 640x480.
This function allows the application to query the clipping area. The default values for the x_position and y_position structure elements are 0. The default values for the width and height are the width and height of the image.
This method allows the application to specify the dimensions of the uncompressed image.
The default uncompressed image size is 640x480. For NTSC the minimum image size is 12x4 and the maximum size is 640x480. For PAL, the minimum image size is 12x8 and the maximum size is 768x576.
The value of the image size has to be even.
| inout long width | Specifies the width of an uncompressed image. |
| inout long height | Specifies the height of an uncompressed image. |
This function allows the application to query the dimensions of the uncompressed image.
| inout long width | Returns the width of an uncompressed image. |
| inout long height | Returns the height of an uncompressed image. |
This method sets the quantization table of the video device. For each table, the size should be 64 bytes long. The valid table ids are 1, 2, 3, and 4. They are in zig-zag order, not in Visi order.
| in string tableid | Specifies the string of the quantization table. The possible values of tableid are QTABLE_A_Y, QTABLE_A_C, QTABLE_B_Y, and QTABLE_B_C. |
typedef struct
{
unsigned long _maximum; Specifies the max. length of q_table
unsigned long _length; Length of q_table
octet *_buffer; The pointer to the q_table
}
_IDL_SEQUENCE_octet Callers must allocate the buffer
This method allows applications to query the quantization table of the video device. For each table, the size is 64 bytes long. The valid table ID are 1, 2, 3, and 4. They are in zigzag order, not in Visi order.
This method sets the Huffman table of the video device. The elements of the table are one byte in size(unsigned char). The tables are of the type bits and values.
This method allows the caller to query the Huffman tables of the video device. The elements of the table are one byte in size(unsigned char). The tables are of the type bits and values.
This method is used to put a compressed frame to the video out device's analog output.
| in long index | Specifies the index of the structure in the ring buffer array that contains the image to be output. |
| WrongIndex | The index does not correspond to the next available buffer |
This method is used to put an uncompressed frame to the video out device's analog output. The data must be YUV422 format. The image size is 640x480.
| in long index | Specifies the index of the structure in the ring buffer array that contains the image to be output. |
| WrongIndex | The index does not correspond to the next available buffer |
This method returns the index of a ring buffer structure that contains a compressed frame from the video device. There is NO JPEG header in the JPEG data. The caller must have previously provided the capture ring buffer.
| BufferNotAvailable | Compressed buffer is not available |
This method returns the index of a ring buffer structure that contains an uncompressed frame from the video device. The caller must have previously provided the capture buffer.
| BufferNotAvailable | Uncompressed buffer is not available and the blocking_flag is set to NON blocking. |
This method returns the index of a ring buffer structure that can be used as a compressed buffer to be output to the video device's analog output.
| BufferNotAvailable | Compressed buffer is not available and the blocking_flag is set to NON blocking. |
This method returns the index of a ring buffer structure that can be used as an uncompressed buffer to be output to the video device's analog output.
| BufferNotAvailable | Uncompressed buffer is not available and the blocking_flag is set to NON blocking. |
This function sets the video input connector. The default value for video_in is INPUT_COMPOSITE.
| in string video_in | The string specifies the video input connector. The possible values of the video_in are INPUT_COMPOSITE and INPUT_SVIDEO. |
This function allows the application to query the setting of the video input connector.
| out string video_in | A string containing the video_in is returned. The possible values of the video_in are INPUT_COMPOSITE and INPUT_SVIDEO. |
This function allows the application to input a JPEG header. This method returns Success if the JPEG header markers are valid. There should be NO JPEG data in the header.
This function returns the size of a JPEG header that contains the desired elements.
This function returns a JPEG header containing the desired elements.
inout sequence <octet> jpeg_header
typedef struct {
unsigned long _maximum; Specifies the max. length of header
unsigned long _length; Length of JPEG header is returned by
VideioIO Object
octet *_buffer; Pointer to the jpeg_header data
}
_IDL_SEQUENCE_octet The caller must malloc the buffer
| in JPEGHeaderFlag flag | This flag sets the information of the JPEG header that application requires. The values are:
enum JPEGHeaderFlag{ NoDQT_DHT, WithDQT, WithDHT, WithDQTandDHT } |
This method enables an area of memory to be used to capture uncompressed video frames. The caller provides the memory containing the video capture buffer.
Attention: The array of structures describing the buffers and the buffers must not share the same page of memory. No single page can be used for more than one buffer or the array of structures. The PAGESIZE definition can be found in /usr/include/sys/parm.h.
An index to this array is returned by the get_uncompressed_frame method.
struct RingBufferElement {
long Address; The pointer for video image buffer.
long AfterHeader; The pointer for video image data not including
the JPEG header.
long SizeOfBuffer; Specifies the maximum image size.
long SizeOfDataInBuffer; Initialize this field to 0. This field is updated by
the device driver after the return of the
get_uncompressed_frame method.
long InUseByCaller; This field is updated by device driver if the buffer
is in use. The caller sets the field to 0 when the
buffer is no longer in use.
long NumberOfOverruns; An indication of how many frames were lost.
Data already in the buffer is not removed until
the InUseByCaller flag is reset.
};
This method enables an area of memory to be used to output uncompressed video frames. The caller provides the memory containing the video output buffer.
Attention: The array of structures describing the buffers and the buffers must not share the same page of memory. No single page can be used for more than one buffer or the array of structures. The PAGESIZE definition can be found in /usr/include/sys/parm.h.
An index to this array is returned by the get_next_uncompressed_video_out_buffer method.
struct RingBufferElement {
long Address; The pointer for video image buffer.
long AfterHeader; The pointer for video image data not including
the JPEG header.
long SizeOfBuffer; Specifies the maximum image size.
long SizeOfDataInBuffer; This field is initialized by the caller.
long InUseByCaller; This field is updated by Device Driver after the
buffer is output.
long NumberOfOverruns; An indication of how many frames were
duplicated while waiting for the next frame to be
output.
};
This method enables an area of memory to be used to capture compressed video frames. The caller provides the memory containing the video capture buffer.
Attention: The array of structures describing the buffers and the buffers must not share the same page of memory. No single page can be used for more than one buffer or the array of structures. The PAGESIZE definition can be found in /usr/include/sys/parm.h.
An index to this array is returned by the get_compressed_frame method.
struct RingBufferElement {
long Address; The pointer for video image buffer.
long AfterHeader; The pointer for video image data not including
the JPEG header.
long SizeOfBuffer; Specifies the maximum image size.
long SizeOfDataInBuffer; Initialize this field to 0. This field is updated by
device driver after the return of the
get_compressed_frame method.
long InUseByCaller; This field is updated by Device Driver if the
buffer is in use. The caller sets the field to 0
when the buffer is no longer in use.
long NumberOfOverruns; An indication of how many frames were lost.
Data already in the buffer is not removed until
the InUseByCaller flag is reset.
};
This method enables an area of memory to be used to output compressed video frames. The caller provides the memory containing the video output buffer.
Attention: The array of structures describing the buffers and the buffers must not share the same page of memory. No single page can be used for more than one buffer or the array of structures. The PAGESIZE definition can be found in /usr/include/sys/parm.h.
An index to this array is returned by the get_next_compressed_video_out_buffer method.
struct RingBufferElement {
long Address; The pointer for video image buffer.
long AfterHeader; The pointer for video image data not including
the JPEG header.
long SizeOfBuffer; Specifies the maximum image size.
long SizeOfDataInBuffer; This field is initialized by the
caller.
long InUseByCaller; This field is updated by Device Driver after the
buffer is output.
long NumberOfOverruns; An indication of how many frames were
duplicated while waiting for the next frame to be
output.
};
This method discards any remaining data in the uncompressed capture buffers.
This method discards any remaining data in the uncompressed output buffers.
This method discards any remaining data in the compressed capture buffers.
This method discards any remaining data in the compressed output buffers.
This method returns the number of compressed frames awaiting output to video out.
| inout long count | Returns the number of compressed frames in the ring buffer awaiting output to video out |
This method returns the number of uncompressed frames awaiting output to video out.
| inout long count | Returns the number of uncompressed frames in the ring buffer awaiting output to video out |
The UMSVideoIO object has the following limitations:
NTSC Supported Rates (FPS): 1 2 3 5 7 15 30 Requested Rate (FPS): 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 30 Resulting Rate (FPS): 1 2 3 5 5 7 7 15 15 15 15 15 15 15 15 30 30 PAL Supported Rates (FPS): 1 2 3 4 6 12 25 Requested Rate (FPS): 1 2 3 4 5 6 7 8 9 10 11 12 13 25 Resulting Rate (FPS): 1 2 3 4 6 6 12 12 12 12 12 12 25 25
The default settings for the monitoring image width and height are those for a full frame. This means that if the image format is changed to 24-bit RGB while the default settings for the monitoring image width and height are still in effect, the monitoring image size must be reduced to a valid size before capturing can commence. The largest valid size for the monitoring image when the image format is 24-bit RGB is 320 x 240 for NTSC and 384 x 288 for PAL.
This problem will eventually be corrected using unique file names. Until that time, you should pay close attention to the order of operations. Do not start a second capture until the first capture is either saved or discarded. Another possible workaround is to start the first application and edit the UMS configuration file to change the name of the temporary fast file. Start the second application after you have made this modification.
For introductory information, see Movie Capture and Playback Objects.