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

UMSVideoDecoder Object

The UMSVideoDecoder object is a base class. Specific video decoder implementations inherit their interface from this class. Ultimedia Services player objects and applications achieve video-decoder independence by accessing the specific decoders through the methods of the base class without the need to know the specific decoder being used.

A metaclass is provided that has a method to construct a specific video decoder based on a user-specified from_format and to_format and data in the configuration file. For example, a from_format of ULTI and a to_format of RGB8Dither would result in construction of an UMSUMVideoDecoder. This allows applications to transparently support new decoders that are added to the installation. It also permits third parties to develop and install new decoders that extend the capabilities of Ultimedia Services.

Alternatively, a specific video decoder object can be constructed by the standard ObjectNameNew method.

To learn more about the UMSVideoDecoder 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 varies with the application. The detailed method descriptions describe the valid or possible values for the specific use. The following are the enumerated lists that are defined for this object.

enum ReturnCode {
   Success, 
   Failure, 
   UnsupportedFormat,
   Uninitialized, 
   OutOfMemory, 
   OutOfRange,
   IncompatibleSettings,
   InvalidArgument,
   UnsupportedValue 
   };

Type Definitions

The UMSVideoDecoder object defines the following types:

Method Descriptions

ReturnCode set_image_format(in ImageFormatOut image_format_out)

Description

This method sets the format of the output image data to be created by the decoder. If the format is unsupported, a ReturnCode value of UnsupportedFormat is returned. The desired output format is specified as a string. The output formats supported are implementation-specific, but common formats include RGB8Dither, YUV9, RGB24, Mono8, BGR24Reverse, and YUV422.

Arguments
in ImageFormatOut image_format_out The string specifies the desired output format. The ImageFormatOut type is defined to be a string.
Return Values

Success

UnsupportedFormat

ReturnCode get_image_format(out ImageFormatOut image_format_out)

Description

This method enables the application to query the output image format. The return value specifies the current setting of the output image format.

Arguments
out ImageFormatOut image_format_out A string containing the current output format is returned. The ImageFormatOut type is defined to be a string.
Return Values

Success

InvalidArgument

ReturnCode set_image_size(in long width, in long height)

Description

This method sets the image dimensions. The image size is the native size of the compressed images to be processed. The default display size is set to the image size. The display size is the size of the output image. Specific decoder implementations which support resizing allow the display image size to be set separately from the image size via the set_display_size method.

Arguments
in long width Specifies the native width of the compressed input images.
in long height Specifies the native height of the compressed input images.
Return Values

Success

InvalidArgument

OutOfMemory

OutOfRange

ReturnCode get_image_size(inout long width, inout long height)

Description

Returns the current image size setting.

Arguments
inout long width The current setting of the native width of the compressed input images is returned.
inout long height The current setting of the native height of the compressed input images is returned.
Return Values

Success

InvalidArgument

ReturnCode set_display_size(in long display_width, in long display_height)

Description

This method allows the display size to be different from the image size for decoders which support resizing. The display size specifies the output image size for the decoder. If set_display_size is never called for an object or if the display size width and height are set to 0, the output image size is the native image size specified with the set_image_size method. The decompression time for decoders can be degraded when the image size and display size are different. It is common for decoders to optimize specific resizing factors--in particular, x2 and other integer factors.

Arguments
in long display_width Specifies the desired width of the output images.
in long display_height Specifies the desired height of the output images.
Return Values

Success

OutOfRange

OutOfMemory

ReturnCode get_display_size(inout long display_width, inout long display_height)

Description

The current display size is returned. A returned width and height of 0 indicates that the display size is the same as the image size. The display size specifies the output image size.

Arguments
inout long display_width The display size width is returned.
inout long display_height The display size height is returned.
Return Values

Success

InvalidArgument

ReturnCode set_colormap_attributes(inout long colormap_base_index, inout long colormap_size)

Description

This method specifies the number of entries the decoder is to have in the color table and the offset of these entries. These are relative to a 256-entry color map with entries indexed from 0 to 255. A specific decoder can be totally flexible in accepting these values, or can only support a specific set of colormap sizes. If the requested colormap size is not supported, the decoder should give a ReturnCode value of UnsupportedValue and set the returned colormap_size to a supported size. If an adjustment to the colormap_size is required, it should be adjusted downward when possible. By convention, the offset returned with the adjustment should claim the highest entries in the colormap. The colormap is required only when the output is RGB8Dither or Mono.

Arguments
inout long colormap_base_index Specifies the offset within a 256-entry colormap where the color entries for dithering should be placed.
inout long colormap_size On input, specifies the number of colormap entries that are requested for dithering the RGB8Dither or Mono output. On output, contains the actual colormap size set by the object.
Return Values

Success

OutOfMemory

OutOfRange

ReturnCode get_colormap_attributes(inout long colormap_base_index, inout long colormap_size)

Description

Reads the color map size and the base index value established for dithering the RGB8Dither output.

Arguments
inout long colormap_base_index Returns the starting index of the colormap entries in the window's colormap.
inout long colormap_size Returns the number of colormap entries.
Return Values

Success

InvalidArgument

ReturnCode get_color_map(inout ColorMap color_map)

Description

Given the offset and length of the colormap to be used for RGB8Dither or Mono output, the decoder determines the entry values of the colormap. This method returns the resulting colormap values in the color_map sequence of octets. The data is returned as a sequence of octets specifying entries of the colormap consecutively, with 4 bytes of data for each entry. The 4 bytes of data are structured as: pad, red, green, and blue. The pad byte exists so that the data structure is compatible with the AIXwindows colormap definition of overlay:red:green:blue

Arguments
inout ColorMap color_map The colormap is returned as a sequence of octets.
Return Values

Success

InvalidArgument

Uninitialized

ReturnCode decompress_frame(in CompressedFrame comp_frame, inout ImageFrame image_frame, in long skip_flag)

Description

The compressed frame input in the comp_frame sequence of octets is decompressed. The resultant output image is returned in the image_frame sequence of octets. Many decoders use delta-frame techniques which require a sequence of frames up to the frame of interest to be processed. The skip_flag parameter is used to signify that no output is desired for the requested frame, meaning that the frame is being processed only to establish state within the decoder. The decoder can optimize the decompression performance based on the knowledge that no output image is required.

Arguments
in CompressedFrame comp_frame The comp_frame sequence contains the compressed image data to be processed.
inout ImageFrame image_frame The output image is returned in the image_frame sequence.
in long skip_flag A nonzero value indicates that no output image is desired and the frame is being processed solely to update the decoder state.
Return Values

Success

Failure

InvalidArgument

OutOfMemory

Uninitialized

ReturnCode set_output_quality(inout OutputQuality output_quality)

Description

Sets the output quality to the value that most closely matches the requested setting. The returned value of OutputQuality is the value that was actually set. The method permits a tradeoff between speed and quality in those video decoder implementations for which that has meaning. The default implementation in the base class is to save the requested value as the current setting.

Arguments
inout OutputQuality output_quality On input, contains the desired value for output quality. On output, contains the resultant value for output quality.
Return Values

Success

Failure

ReturnCode get_output_quality(inout OutputQuality output_quality)

Description:

The current output quality setting is returned.

Arguments
inout OutputQuality output_quality The current output quality value is returned.
Return Values

Success

InvalidArgument

OutOfRange

Error Return Codes

The UMSVideoDecoder object can return any of the following error codes. A brief description of each error code is given along with some possible reasons for the error code. Note that the UMSVideoDecoder is a class interface specification and each video decoder class that inherits from this class implements that actual method behavior.

Error Code Description
Uninitialized Indicates that some necessary parameters have not been set in one of the object's other methods. Typically, an object has setup methods and process methods. This error is typically invoked for a process method, if some state has not been set in one of the setup methods.

Example:   Calling decompress_frame method before setting the image size.

OutOfRange Any input arguments that can be range-checked are tested for valid range.

Example:   Image dimensions less than zero; color map size greater than 256.

Failure Indicates any type of method execution failure. All required setup was performed and the input arguments were valid, but the method did not complete successfully.

Example: decompress_frame is called and a problem is encountered while processing the compressed data file.

IncompatibleSettings This error indicates that two different methods individually have valid settings, but together make it impossible to perform the data transformation step.

Example: Resizing request for a YUV output format.

InvalidArgument One of the supplied input arguments contains a value that is not within a valid range. The processing for this method cannot proceed.

Example: For sequences, common errors include: NULL input structure pointer, NULL input buffer pointer, and _maximum length zero or too small to hold the amount of data to be supplied. For methods that supply a pointer for a returned data value, NULL pointers also generate this error.

UMSJPEGVideoDecoder Object

The following method is implemented in this class but is not part of the base class. In most cases, this method is unnecessary as the same information can be extracted from the file that contains the JPEG image or video sequence.

UMSVideoDecoder::ReturnCode get_component_number( in UMSVideoDecoder::CompressedFrame comp_frame, inout long component_number)

Arguments
comp_frame A pointer to the JPEG compressed frame. The compressed frame contains the header data that is parsed by this method to extract the component number. The JPEG file format supports multiple color components. For example, an RGB image is stored as three separate color components.
component_number A pointer to the variable to receive the number of color components stored in the compressed frame.

For introductory information, see Video Codec Objects.


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