UMSVideoDecoder

The UMSVideoDecoder is a base class. Specific video decoder implementations inherit their interface from this class. Currently, the particular decoders in the class are the UMSJPEGVideoDecoder, UMSH261VideoDecoder, UMSH263VideoDecoder, UMSUMVideoDecoder, UMSIndeoVideoDecoder, UMSIndeo3VideoDecoder, and UMSRTV2VideoDecoder objects. These objects support JPEG/MJPEG, H.261, H.263, Ultimotion Matinee, Indeo 2.1, Indeo 3.1/3.2, and RTV 2.0/2.1 video. Codec developers are able to add new decoders to this class.

The UMSVideoDecoder object allows an application to be unaware of the particular decoder it is calling. The application can create a specific decoder either directly by the standard ObjectNameNew method or automatically using a configuration file and methods in the UMSVideoDecoderMClass metaclass.

Each real decoder implements the interface methods according to some common behavioral rules and the requirements of its core algorithms. Therefore, the basic behavior of UMSVideoDecoder methods is independent of the particular decoder; beyond that, the specific decoders share a common set of return codes and behave in a predictable fashion. Each decoder has its own algorithm-specific error traps. Also, different decoders can support different image formats, quality levels, and so forth. The returned parameters and error codes should allow the application to call methods in a codec-independent fashion.

The UMSVideoDecoder interface allows a decoder to support three useful functions beyond the usual decoder setup and decompression methods. First, it allows the decoder to implement different quality levels in its output frames; this allows a tradeoff between output quality and frame rate beyond the usual frame-skipping. Second, the interface allows for arbitrary resizing of the output frames. Third, an application can query a decoder for a list of the formats that the decoder supports.

The UMSVideoDecoder class is descended from the UMSNegotiatorSource class. Basically, the methods from the UMSVideoDecoder class that set and query image formats map to "generic" methods in the UMSNegotiatorSource class. The UMSNegotiatorSource and UMSNegotiatorSink classes provide a "generic" interface for connecting objects that produce data ("source" objects) and objects that consume data ("sink" objects).

Note: The UMSVideoDecoder class replaces the decoder objects in Ultimedia Services 1.0. The Ultimedia Services 1.0 decoder objects are still available but should not be used for further development.

To learn more about using the UMSVideoDecoder, see:

• Decoding Frames with the UMSVideoDecoder Object
• Tips for Using the UMSVideoDecoder

For introductory information, see Programming with Video Codec Objects.

Decoding Frames with the UMSVideoDecoder Object

To decode frames using the UMSVideoDecoder object, do the following:

1. Create the particular decoder object and its associated filereader or collaboration (network connection) object.
2. Open the input file or set up the network connection.
3. Set the format of the output frames with the set_image_format method.
4. If the image format is RGB8Dither, call set_colormap_attributes to set the dithering/colormap parameters, and then call get_colormap to get the decoder's colormap. Insert this colormap into the colormap for the output window.
5. Set the native dimensions of the decompressed frames with the set_image_size method.
6. Optionally, call the set_display_size method to set the size of the frames at the output of the decoder.
7. Allocate memory for the compressed and decompressed frames, and insert them into SOM sequence structures. Optionally, use the get_max_output_buffer_size method to get the size of the output buffer.
8. Optionally, call set_output_quality to set the quality of the output frames.
9. Get each compressed frame and decompress it with the decompress_frame method.

When the video is finished, close the input file or network connection, free the input and output buffers and SOM sequence structures, and destroy the decoder and filereader or collaboration objects with _somFree.

Decoder Options and Defaults

The decoder options and defaults are as follows:

UMSH261VideoDecoder

Supported formats:

• F_YUV420Plane
• IF_YUV422
• IF_RGB8Dither
• Mono

Frame Sizes:

• 176x144
• 352x288

Colormap Parameters:

• IF_RGB8Dither (size = 224)
• base (index = 32)
• Mono (size = 64)
• index arbitrary

Resizing:

• 2x resizing of IF_RGB8Dither
• Mono

Output Quality:

• 2 levels of quality in resizing of IF_RGB8Dither

Defaults:

UMSH263VideoDecoder

Supported formats:

• IF_YUV420Plane
• IF_YUV422
• IF_RGB8Dither
• Mono

Frame Sizes:

• 128x96
• 176x144
• 352x288

Colormap Parameters:

Resizing:

• 2x resizing of IF_RGB8Dither
• Mono

Output Quality: 2 levels of quality in resizing of IF_RGB8Dither

Defaults:

UMSIndeoVideoDecoder

Supported formats:

• IF_YUV9
• IF_YVU9
• IF_YUV422
• IF_PadRGB24
• IF_PadBGR24Reverse
• IF_RGB8Dither

Colormap Parameters:

Resizing: arbitrary resizing of RGB formats; fast 1x2, 2x1, 2x2

Output Quality: 3 quality levels

Defaults:

UMSIndeo3VideoDecoder

Supported formats:

• IF_YUV9
• IF_YVU9
• IF_YUV422
• IF_PadRGB24
• IF_PadBGR24Reverse
• IF_RGB8Dither

Colormap Parameters:

Resizing:

• arbitrary resizing of RGB formats; fast 1x2, 2x1, 2x2

Output Quality

• 2 quality levels

Defaults

UMSJPEGVideoDecoder

Supported formats:

• IF_MJPEG (passthrough)
• IF_YUV422
• IF_PadRGB24
• IF_RGB8Dither
• Mono
• RGB (planar - one plane each of R, G, and B)

Colormap Parameters:

Resizing: arbitrary resizing of RGB except for IF_RGB8Dither with colormap size = 224

Output Quality: one quality level

Defaults:

UMSRTV2VideoDecoder

Supported formats:

• IF_YUV9
• IF_YVU9
• IF_YUV422
• IF_PadRGB24
• IF_PadBGR24Reverse
• IF_RGB8Dither

Colormap Parameters: IF_RGB8Dither size = 64, 128, 256; base index arbitrary

Resizing: arbitrary resizing of RGB formats; fast 1x2, 2x1, 2x2

Output Quality: 3 quality levels

Defaults:

UMSUMVideoDecoder

Supported formats:

• IF_YUV9
• IF_YUV422
• IF_PadRGB24
• IF_PadBGR24Reverse
• IF_RGB8Dither
• Mono

Colormap Parameters: IF_RGB8Dither size = 64, 128, 256; base index arbitrary

Resizing: arbitrary resizing of RGB formats

Output Quality: one quality level

Defaults:

Tips for Using the UMSVideoDecoder

The following tips provide important information for using the UMSVideoDecoder:

• Indeo, Ultimotion Matinee, and (commonly) JPEG video frames are packaged in Microsoft's AVI file format. RTV 2.0/2.1 uses the AVSS file format. H.261 and H.263 are transmitted by a variety of mechanisms, including Real Time Protocol (RTP) and the ITU Recommendations H.320, H.323, H.324, etc.
• Frame dimensions less than 1 or greater than 4096 or otherwise not supported by a decoder will cause an error.
• The current decoders support resizing. Typically, a decoder supports resizing for RGB formats only, not YUV formats. Some decoders support arbitrary resizing while others support 2x resizing only. Typically, resizing slows down a decoder; some decoders have optimized routines for simple cases such as 2x.
• If set_display_size is not called, or if it is called with dimensions of 0, the dimensions of the output frames match the native dimensions of the compressed frames.
• RTV 2.0/2.1 video should be widened by 25% before display. Use the set_display_size method to accomplish this.
• All the decoders support the RGB8Dither format. Most support at least one YUV format and at least one 24-bit RGB format (PadRGB24).
• Each decoder maps a requested colormap size to one that it actually supports. Commonly supported colormap sizes are 64, 128, 224, and 256.
• The UMSJPEGVideoDecoder and UMSUMVideoDecoder objects each support only one quality level. The other decoders each support 2 or 3 quality levels. The UMSH261VideoDecoder and UMSH263VideoDecoder objects only support two quality levels when resizing the RGB8Dither format. The set_output_quality method can be called at any time.
• For RTV video in AVSS, if the UMSAVSReadWrite object's get_video_chunk_size method returns a value between 0 and 16, the video chunk has no data and should be skipped.
• To skip a frame while maintaining the correct state in a decoder object, call the decompress_frame method with skip_flag set to 1. The decoder updates its state, but does not create an output frame.

For introductory information, see Programming with Video Codec Objects.