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

UMSIndeo3Encoder Object

The UMSIndeo3Encoder object provides methods to compress video frames to the Indeo 3.2 video format. It is presented in the class library for editing and format conversion purposes.

To learn more about the UMSIndeo3Encoder object, see:

For introductory information, see Video Codec Objects.

Type Definitions

The UMSIndeo3Encoder object defines the following types:

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 enumerated lists that are defined for this object are listed below.

enum ReturnCode {
   Success, 
   Failure, 
   UnsupportedFormat,
   UnsupportedAlgorithm, 
   OutOfRange,
   Uninitialized, 
   OutOfMemory,
   InvalidArgument
    }
enum ImageFormatIn {
   YUV9, 
   RGB24,
   YVU9
   }
enum FrameType {
   Reference, 
   Delta
   }

Method Descriptions

ReturnCode set_image_format(in ImageFormatIn indeo_enc_image_format)

Description

This method sets the format that the encoder expects for the input frames. If an invalid format is specified, then the method returns the error code UnsupportedFormat; otherwise, the method returns Success.

Arguments
in ImageFormatIn indeo_enc_image_format Specifies the format of the input frame.
Return Values

Success

UnsupportedFormat

ReturnCode get_image_format(inout ImageFormatIn indeo_enc_image_format)

Description

This method queries the current input image format.

Arguments
inout ImageFormatIn indeo_enc_image_format The current setting of the input image format.
Return Values

Success

InvalidArgument

ReturnCode set_image_size(in long width, in long height)

Description

This method sets the frame width and height parameters, and mallocs the internal frame buffers for the UMSIndeo3Encoder object. If either of the input dimensions is not a multiple of 4, the method sets up the encoder to encode a subframe of each input frame. The subframe starts at the top left corner of the input frame, and has dimensions that are multiples of 4. If either of the requested dimensions is negative or greater than 4096, the method returns OutOfRange. If a malloc fails, the method returns OutOfMemory; otherwise, it returns Success.

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

Success

OutOfMemory

OutOfRange

ReturnCode get_image_size(inout long width, inout long height)

Description

This method queries the frame width and height parameters.

Arguments
inout long width Current setting of the frame width.
inout long height Current setting of the frame width.
Return Values

Success

InvalidArgument

ReturnCode set_subimage_size(in long sub_xpos, in long sub_ypos, in long sub_width, in long sub_height)

Description

This method sets the position and size of the subimage of the input frame that should be encoded. It truncates the subframe width and height to multiples of 4. The position parameters refer to the top left corner of the subframe; (0, 0) refers to the top left corner of the full input frame.

Arguments
in long sub_xpos The offset, within the input image, to begin encoding in the x direction.
in long sub_ypos The offset, within the input image, to begin encoding in the y direction.
in long sub_width Width of the subimage to be endcoded.
in long sub_height Height of the subframe to be encoded.
Return Values

Success

Failure

OutOfRange

OutOfMemory

ReturnCode get_subimage_size(inout long sub_xpos, inout long sub_ypos, inout long sub_width, inout long sub_height)

Description

This method queries the subimage size and position parameters. If set_subimage_size has not been called, these have the values set by the last call to set_image_size, if any; otherwise, they have the values set by the last call to set_subimage_size.

Arguments
inout long sub_xpos The offset, within the input image, to begin encoding in the x direction.
inout long sub_ypos The offset, within the input image, to begin encoding in the y direction.
inout long sub_width Width of the sub-frame to be encoded.
inout long sub_height Height of the sub-frame to be encoded.
Return Values

Success

InvalidArgument

ReturnCode get_max_buffer_size(inout long buffer_size)

Description

This method computes an upper limit on the size of the output buffer for the encoder. The application should use this size to malloc a buffer to receive the compressed frames. The size depends on the dimensions of the input frames.

Arguments
inout long buffer_size The maximum size of a compressed image.
Return Values

Success

InvalidArgument

ReturnCode compress_frame_RC(in ImageFrame image_frame, inout CompressedFrame comp_frame, in FrameType frame_type, in long initial_quality_factor, inout long final_quality_factor, in long Length)

Description

This method compresses an input frame with bitrate control. First, the method compresses the frame with the initial_quality_factor setting. Thereafter it decreases the internal quality level and recompresses the frame until the size of the compressed frame is just less than or equal to the length parameter. After compressing the frame for the last time, the method computes a final_quality_factor.

If the initial_quality_factor is less than 0 or greater than 100, or if the length parameter is not positive, the method returns OutOfRange. Otherwise, the method behaves similarly to the compress_frame_QF method.

Arguments
in ImageFrame image_frame An ImageFrame sequence containing data to be compressed.
inout CompressedFrame comp_frame A CompressedFrame sequence containing the compressed frame.
in FrameType frame_type The requested frame type.
in long initial_quality_factor The starting quality factor to use as the initial value for compressing the frame; if the value results in a frame that is too large, the quality factor is changed by the method as it attempts to compress the file to the desired size. The valid range is 0 to 100 (lowest to highest quality).
inout long final_quality_factor The quality factor used to compress the frame.
in long Length The desired average length of the compressed frame in bytes.
Return Values

Success

Failure

InvalidArgument

OutOfMemory

OutOfRange

ReturnCode compress_frame_QF(in ImageFrame image_frame, inout CompressedFrame comp_frame, in FrameType frame_type, in long quality_factor)

Description

This method compresses an input frame according to a requested quality and frame type. The frame types are Reference, and Delta; the quality factor can vary between 0 and 100.

Arguments
in ImageFrame image_frame An ImageFrame sequence containing data to be compressed.
inout CompressedFrame comp_frame A CompressedFrame sequence containing the compressed frame.
in FrameType frame_type The requested frame type.
in long quality_factor A value between 0 and 100 that influences image quality. A higher value corresponds to a larger encoded frame size and higher image quality.
Return Values

Success

Failure

InvalidArgument

OutOfMemory

OutOfRange

For introductory information, see Video Codec Objects.


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