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.
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
};
The UMSVideoDecoder object defines the following types:
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.
| in ImageFormatOut image_format_out | The string specifies the desired output format. The ImageFormatOut type is defined to be a string. |
This method enables the application to query the output image format. The return value specifies the current setting of the output image format.
| out ImageFormatOut image_format_out | A string containing the current output format is returned. The ImageFormatOut type is defined to be a string. |
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.
| in long width | Specifies the native width of the compressed input images. |
| in long height | Specifies the native height of the compressed input images. |
Returns the current image size setting.
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.
| in long display_width | Specifies the desired width of the output images. |
| in long display_height | Specifies the desired height of the output images. |
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.
| inout long display_width | The display size width is returned. |
| inout long display_height | The display size height is returned. |
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.
Reads the color map size and the base index value established for dithering the RGB8Dither output.
| 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. |
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
| inout ColorMap color_map | The colormap is returned as a sequence of octets. |
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.
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.
| inout OutputQuality output_quality | On input, contains the desired value for output quality. On output, contains the resultant value for output quality. |
The current output quality setting is returned.
| inout OutputQuality output_quality | The current output quality value is returned. |
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.
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.
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.
For introductory information, see Video Codec Objects.