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

UMSRTV2Decoder Object

The RTV 2.0 decoder object provides methods to decompress the RTV 2.0/2.1 video format. It is presented in the class library for editing and format-conversion purposes.

Note: The UMSRTV2Decoder object is shipped for compatibility with the Ultimedia Services Version 1.1.0 product. The function provided is redundant with the UMSRTV2VideoDecoder object. The UMSRTV2VideoDecoder object is the preferred object for decoding RTV 2.0 or 2.1 video, since it inherits methods from the UMSVideoDecoder base video decoder class.

To learn more about the UMSRTV2Decoder object, see:

For introductory information, see Video Codec Objects.

Enumeration Lists

To avoid name collision on defines, integer values have been captured as enumerated lists. The set of valid values from an enumerated list can vary with the application. The detailed method descriptions describe the valid or possible values for the specific use. The enumerated lists that are defined for this object are:

enum ReturnCode {
   Success, 
   Failure, 
   UnsupportedFormat, 
   UnsupportedAlgorithm, 
   OutOfRange, 
   Uninitialized, 
   OutOfMemory 
   };
enum RTV2DecImageFormatOut {
   RGB8Dither, 
   YUV9, 
   RGB24, 
   BGR24Reverse 
   };
enum RTV2DecOutputQuality {
   Low, 
   Medium, 
   High 
   };

Frame Header

An RTV 2.0 frame header has the following header, which it shares with other video codecs within the AVSS file format:

U16 AlgorithmNumber

AlgorithmNumber is 200 (to specify RTV 2.0). Other values in this field indicate other versions of RTV or other algorithms (such as JPEG).

U16 StillFlag

StillFlag indicates whether the compressed data that follows represents an I frame or a delta frame. An I frame can be decoded by itself, while a delta frame requires the previous decoded frame to generate an output frame. If bit 2 of StillFlag is 1, the compressed data represents an I frame; otherwise, it represents a delta frame.

The other bits of StillFlag can be used to indicate the possibility of frame skipping, the number of frames to the next I frame, and so forth, but are not used by the UMSRTV2Decoder object.

U32 DataSize

DataSize gives the size of the compressed frame (including the header) in bits. This entry is ignored by the UMSRTV2Decoder object.

U32 Reserved.
U16 ImageHeight
U16 ImageWidth

ImageHeight and ImageWidth give the height and width of the final decoded image. RTV 2.0 uses only two sizes: 256 x 240 and 128 x 120.

Method Descriptions

ReturnCode decompress_frame(in char *comp_frame, in char *image_frame)

Description

This method decompresses a frame and formats it as requested by set_image_format. It can be mixed freely with the decompress_frame_only method.

Begin decompression at an I frame. The format for a compressed frame is described in the preceding text.

Arguments
in char *comp_frame Pointer to the start of the compressed frame data.
in char *image_frame Pointer to the start of the decompressed image data.
Return Values

Success

Failure Returns Failure if comp_frame or image_frame is NULL or if the ImageWidth and ImageHeight parameters in the frame header do not match the values that were set by the last call to set_image_size (or SomInit).
UnsupportedAlgorithm Returns UnsupportedAlgorithm if the AlgorithmNumber parameter in the frame header is not 200.
OutOfRange Returns OutOfRange if the ImageWidth and ImageHeight parameters are not 128 x 120 or 256 x 240, or if either the output format or output quality is invalid.

ReturnCode decompress_frame_only(in char *comp_frame)

Description

This method decompresses a frame and updates the decoder's internal buffers, but does not produce the final output frame. It allows for frame skipping in the displaying application, while maintaining the correct state in the decoder. It can be mixed freely with the decompress_frame method.

Begin decompression at an I frame. The format for a compressed frame is described in the preceding text.

Arguments
in char *comp_frame Pointer to the start of the compressed frame data.
Return Values

Success

Failure Returns Failure if comp_frame or image_frame is NULL or if the ImageWidth and ImageHeight parameters in the frame header do not match the values that were set by the last call to set_image_size (or SomInit).
OutOfRange Returns OutOfRange if the ImageWidth and ImageHeight parameters are not 128 x 120 or 256 x 240.
UnsupportedAlgorithm Returns UnsupportedAlgorithm if the AlgorithmNumber parameter in the frame header is not 200.

ReturnCode get_color_map(in char *color_map)

Description

This method copies the decoder's color map table to a memory area provided by the calling application. It returns the Failure error code if the pointer color_map is NULL or if the internal color map pointer is NULL; otherwise, it returns Success.

The action of this method is independent of the current image format. You can call set_image_format before or after a call to this method with identical results.

This method can be called at any time during the decoding of a video clip.

In general, the application needs to reformat the color map for the windows systems it uses. For AIXwindows, the color map entries should be converted to AIXwindows format color map entries and should be copied (in the same order as they appear) into a contiguous series of cells in the window's color map.

Arguments
in char *color_map A pointer to a reserved memory area in the application space that can be used to copy the color map from the decoder to the application. Each color entry is a 4-byte value formatted as follows:
Overlay : Red : Green : Blue      - Entry 0
Overlay : Red : Green : Blue      - Entry 1
.
Overlay : Red : Green : Blue      - Entry Size - 1 
Return Values

Success

Failure

ReturnCode get_colormap_attributes(out long colormap_base_index, out long colormap_size)

Description

This method gets the attributes for the color map used by the decoder to create the image frame.

The method always returns Success.

Arguments
out long colormap_base_index The base address of the decoder's color map in the output window's color map.
out long colormap_size The number of color entries in the color map.
Return Values

Success

ImageFormatOut get_image_format()

Description

This method returns the current output image format.

Return Values

Any of the values from the enumerated list RTV2DecImageFormatOut are possible.

ReturnCode get_image_size(out long width, out long height)

Description

This method queries the frame width and height parameters. If set_image_size has not been called, the parameters have the default values; otherwise, they have the values set by the last call to set_image_size. The method always returns Success.

Arguments
out long width Width of the decompressed frame.
out long height Height of the decompressed frame.
Return Values

Success

OutputQuality get_output_quality()

Description

This method returns the output quality, as last set by set_output_quality or SomInit.

Return Values

The output quality setting for the decoder.

ReturnCode set_colormap_attributes(in long colormap_base_value, in long colormap_size)

Description

This method sets up the characteristics of the decoder's internal color map and dithering algorithm. It can be called at any time, but it affects only the RGB8Dither output format.

Arguments
in long colormap_base_value The starting index of the decoder's color map when it is formatted and inserted into the display window's color map.
in long colormap_size The requested number of colors in the color map. It is quantized to a power of 2.
Input Size Color Map Size
0...63 64
64 ... 127 64
128 ... 255 128
256 256
Return Values

Success

Failure The method returns the Failure error code if, for some reason, the internal pointer to the internal copy of the color map is NULL.
OutOfRange The method returns OutOfRange if colormap_base_value is less than 0 or if colormap_base_value + colormap_size is greater than 256. Note that a negative value of colormap_size is quantized to 64.

ReturnCode set_image_format (in ImageFormatOut image_format)

Description

This method sets the format of the output frames to be created by the decoder. If an invalid format is specified, the method returns the UnsupportedFormat error code; otherwise, the method returns Success.

Arguments
in ImageFormatOut image_format Any of the values from the RTV2DecImageFormatOut enumerated list are possible.
Return Values

Success

UnsupportedFormat

ReturnCode set_image_size(in long width, in long height)

Description

This method sets the frame width and height parameters, and allocates the internal frame buffers for the object. The first frame decoded after changing the image size must be an I frame.

Arguments
in long width Width of the decompressed frame.
in long height Height of the decompressed frame.
Return Values

Success

OutOfMemory

ReturnCode set_output_quality (in OutputQuality output_quality)

Description

This method sets the output quality for all frames until the next time the method is called; it can be called at any time.

Arguments
in OutputQuality output_quality The desired output quality.
Return Values

Success

Failure The method returns Failure if the output_quality is invalid.

For introductory information, see Video Codec Objects.


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