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

UMSRTV2Encoder Object

The UMSRTV2Encoder object provides methods to compress video frames to the RTV 2.1 image format. It is presented in the class library for editing and format conversion purposes.

To learn more about the UMSRTV2Encoder 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 enumerated lists that are defined for this object are listed below.

enum ReturnCode {
   Success,
   Failure, 
   UnsupportedFormat,
   UnsupportedAlgorithm, 
   OutOfRange,
   Uninitialized, 
   OutOfMemory
    }
enum ImageFormatIn {
   YUV9, 
   RGB24 
   }
enum FrameType {
   Reference, 
   PeriodRef
   Delta 
   }
enum Scale {
   Full, 
   Half
    }

Type Definitions

The UMSRTV2Encoder object defines the following types:

Method Descriptions

ReturnCode set_image_format(in ImageFormatIn rtv2_enc_image_format)

Description

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

Arguments
in ImageFormatIn rtv2_enc_image_format Specifies the format of the input image.
Return Values

Success

UnsupportedFormat

ReturnCode get_image_format(inout ImageFormatIn rtv2_enc_image_format)

Description

Queries the current input image format. It always returns Success.

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

Success

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 UMSRTV2Encoder object. If either of the input dimensions is not a multiple of 8, 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 8. 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

Queries the frame width and height parameters. It always returns Success.

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

Success

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 8. 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 Number of pixels in x to encode.
in long sub_height Number of pixels in y to encode.
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 default values; 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 subframe to be encoded.
inout long sub_height Height of the subframe to be encoded.
Return Values

Success

ReturnCode set_scale_flags(in Scale xscale, in Scale yscale)

Description

This method sets the flags that control subsampling of the input before the actual compression; RTV allows for subsampling by 2:1 in either or both directions before compression. This method also (re-)mallocs the image buffers.

Arguments
in Scale xscale Specifies full or half image size in the x dimension.
in Scale yscale Specifies full or half image size in the y dimension.
Return Values

Success

OutOfRange

OutOfMemory

ReturnCode get_scale_flags(inout Scale xscale, inout Scale yscale)

Description

Queries the current settings for the scaling in the x and y dimension.

Arguments
inout Scale xscale Specifies full or half image size in the x dimension.
inout Scale yscale Specifies full or half image size in the y dimension.
Return Values

Success

ReturnCode get_max_buffer_size(inout long buffer_size)

Description

This method returns 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

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. If the size of the compressed frame in bytes is less than or equal to the length parameter, the method returns. Otherwise, the method decreases the internal quality level and recompresses the frame until the size of the compressed frame is 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 the frame to be compressed.
inout CompressedFrame comp_frame A CompressedFrame sequence containing the compressed frame is returned.
in FrameType frame_type On input, the requested frame type; the encoder returns the actual frame type used.
in long initial_quality_factor The starting quality factor to be used 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 length of the compressed frame in bytes.
Return Values

Success

Failure

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.

If the requested frame type is Delta, the encoder first compares the input frame to its internal copy of the previous reconstructed (compressed/decompressed) frame. If the difference is large, the encoder switches the variable frame_type to Reference for the current frame. This occurs where there are scene changes or fast motion.

Arguments
in ImageFrame image_frame An ImageFrame sequence containing the frame to be compressed.
inout CompressedFrame comp_frame A CompressedFrame sequence containing the compressed frame is returned.
in FrameType frame_type On input, the requested frame type; the encoder returns the actual frame type used.
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

OutOfMemory

OutOfRange

For introductory information, see Video Codec Objects.


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