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

UMSH261Encoder Object

The UMSH261Encoder object allows the user to compress video frames into H.261 compressed frames. H.261 is a recommendation of the International Telecommunications Union (ITU). The interface for the object is essentially a combination of those for the UMSMPEG1VideoEncoder and UMSH263Encoder objects.

This object can accept input image data in either YUV (YCbCr) or RGB formats. The encoder will accept frame sizes of 352x288 (CIF) and 176x144 (QCIF); the encoding is proportionately slower for CIF input frames. The compressed bit rate can be set to any positive value up to 2 Mbits/sec.

The encoded frame rate can be set to approximately 7.5, 10, 15, or 30 fps. Note that the actual encoding speed depends on the frame size, video content, frequency of P-frames, amount of CPU used, and other factors. For a given requested bit rate, the quality of the decoded frames will increase as the frame rate is decreased. Also, in general, the video quality will increase if P-frames are used, but the encoding will be slower than I-frame-only encoding.

There are two modes for the frame rate--fixed and variable--that are implemented in two different compression methods. In the fixed case, the encoder compresses frames to be played back at the specified rate. In the variable case, the setting is treated as a maximum, and the encoder varies the playback rate for the frames to try to maximize the video quality.

Although H.261 does not distinguish between I-frames and P-frames, the UMSH261Encoder object can compress a frame as an I-frame or as a P-frame. The interface for determining the frame type for each frame is similar to that for the UMSMPEG1VideoEncoder object.

To learn more about the UMSH261Encoder object, see:

For introductory information, see Video Codec Objects.

Enumeration Lists

enum ReturnCode   {
   Success,      // Command completed successfully
   Failure,      // Bad parameter or execution failure 
   UnsupportedFormat,   // Input image format is not supported
   OutOfRange,   // Bad input parameter value 
   Uninitialized,   // Uninitialized state variable
   OutOfMemory,   // Failure trying to allocate internal memory
   UnsupportedValue,   // The parameter value requested is not supported 
   };
enum ImageFormatIn {
   YUVPlanar,   // YUV 4:2:0 planar; same as for MPEG encoder
   YUV422,      // YUV 4:2:2 interleaved format
   RGB24,      // 32-bits/pixel raster; each pixel is 0RGB
   BGR24      // 32-bits/pixel raster; each pixel is 0BGR
   };
enum FrameType     {
   FirstFrame,   // First frame of the sequence
   IFrame,      // Intra-frame
   PFrame,      // Predicted frame
   Unspecified   // Frame type controlled by the encoder
   };
enum FrameRate     {
   R_7Point5,   // 7.493 fps
   R_10,      // 9.990 fps 
   R_15,      // 14.985 fps 
   R_30,      // 29.970 fps
   };
typedef sequence<octet> CompressedFrame;
typedef sequence<octet> ImageFrame;

Method Descriptions

ReturnCode compress_frame( in ImageFrame image_frame, inout CompressedFrame comp_frame, inout FrameType frame_type )

Description

This method compresses an input image frame, and stores the result in the buffer supplied by the user. In addition, the user may specify the frame type for the compressed frame. The first frame in a sequence must be compressed as a FirstFrame. The remaining frames may be compressed as an arbitrary mixture of IFrame and PFrame. If any of these frames are labeled Unspecified, then the encoder uses the I-frame interval to determine the frame type and return the frame type to the user.

Arguments
in ImageFrame image_frame A pointer to a SOM sequence structure to hold the input frame.
inout CompressedFrame comp_frame A pointer to a SOM sequence structure to hold the compressed frame.
inout FrameType frame_type A pointer to an enum variable for the frame type. This argument specifies the frame type requested by the user and the actual frame type encoded. If the user selects Unspecified, then the encoder informs the user what type of frame was encoded.
Return Values

Success

OutOfRange

ReturnCode get_bits_per_second( inout long bits_per_second )

Description

This method queries the bit rate setting.

Arguments
inout long bits_per_second A pointer to a long variable to receive the bits-per-second setting.
Return Values

Success

OutOfRange

ReturnCode get_frame_rate( inout FrameRate frame_rate )

Description

This method queries the frame rate setting.

Arguments
inout FrameRate frame_rate A pointer to an enum variable to receive the frame rate setting.
Return Values

Success

Failure

ReturnCode get_iframe_interval( inout long iframe_interval )

Description

This method queries the I-frame interval setting.

Arguments
inout long iframe_interval A pointer to a variable to receive the I-frame interval setting.
Return Values

Success

OutOfRange

ReturnCode get_image_format( inout ImageFormatIn image_format )

Description

This method queries the image format setting.

Arguments
inout ImageFormatIn image_format A pointer to an enum variable to receive the input image format.
Return Values

Success

OutOfRange

ReturnCode get_image_size( inout long width, inout long height )

Description

This method queries the input image dimensions.

Arguments
inout long width A pointer to a variable to receive the width of the input frames.
inout long height A pointer to a variable to receive the height of the input frames.
Return Values

Success

OutOfRange

ReturnCode get_max_buffer_size( inout long buffer_size )

Description

This method computes a safe size for the output buffer so that it can hold any compressed frame returned by the encoder. The computed buffer size depends on the dimensions of the input frames.

Arguments
inout long buffer_size A pointer to a variable to receive the required buffer size.
Return Values

Success

OutOfRange

ReturnCode get_max_quantization( inout long max_quantization_value)

Description

This method queries the setting of the maximum quantizer step size.

Arguments
inout long max_quantization_value A pointer to a variable to receive the maximum quantizer step size.
Return Values

Success

OutOfRange

ReturnCode get_motion_displacement( inout long displacement)

Description

This method queries the maximum motion displacement to be used in the motion estimation in the encoder.

Arguments
input long displacement A pointer to a variable to receive the maximum motion displacement.
Return Values

Success

OutOfRange

ReturnCode get_packet_info( inout long packet_header, inout long start_offset, inout long packet_size)

Description

This method retrieves information that defines the next RTP packet. The application uses this information with the last compressed frame to construct the packet. It extracts the packet_size in bytes from the compressed frame, beginning from the start of the frame with an offset of start_offset bytes, and concatenates these bytes with the packet_header word.

Arguments
inout long packet_header A pointer to the 32-bit header for the RTP packet.
inout long start_offset A pointer to the starting offset for the packet data in the compressed frame.
inout long packet_size A pointer to the length of the packet data in bytes.
Return Values

Success

OutOfRange

ReturnCode get_packet_size( inout long packet_size)

Description

This method queries the setting for the maximum size for the the RTP packets. The size returned is given in bytes and does not include the 4 bytes for the packet header.

Arguments
inout long packet_size A pointer to a variable to receive the maximum packet size.
Return Values

Success

OutOfRange

ReturnCode set_bits_per_second( in long bits_per_second )

Description

This methods sets the average number of bits allocated for one second of video. By adjusting the quality level for each frame, the encoder attempts to maintain a fairly constant data rate. Note that it may be impossible for the encoder to meet the desired bit rate for a particular combination of input video sequence and encoder parameters.

Arguments
in long bits_per_second The requested bit rate.
Return Values

Success

OutOfRange

ReturnCode set_frame_rate( in FrameRate frame_rate )

Description

This method selects the frame rate from the range of permissible values.

Arguments
in FrameRate frame_rate The enum value for setting the frame rate.
Return Values

Success

OutOfRange

ReturnCode set_iframe_interval( in long iframe_interval )

Description

This method sets the frequency of I-frames within the video sequence.

Arguments
in long iframe_interval The number of compressed frames from the start of one I-frame to the next.
Return Values

Success

OutOfRange

ReturnCode set_image_format( in ImageFormatIn image_format )

Description

This method selects the input image format.

Arguments
in ImageFormatIn image_format An enum variable to specify the input image format.
Return Values

Success

Failure

ReturnCode set_image_size( in long width, in long height )

Description

This method sets the width and height that the encoder expects for the input frames.

Arguments
in long width The width of the input frames.
in long height The height of the input frames.
Return Values

Success

OutOfRange

ReturnCode set_max_quantization( inout long max_quantization_value)

Description

This method set the maximum quantizer step size to be used in the encoder. This value can range from 1 and 31. The encoder returns the value actually used.

Arguments
inout long max_quantization_value A pointer to the variable to set/receive the quantizer step size.
Return Values

Success

OutOfRange

ReturnCode set_motion_displacement( inout long displacement)

Description

This method sets the maximum motion displacement to be used in the motion estimation in the encoder. It should be between 0 and 15. A value of 0 turns the motion estimation off. The object returns the value actually used.

Arguments
inout long displacement A pointer to the variable to set/receive the maximum motion displacement.
Return Values

Success

OutOfRange

ReturnCode set_packet_size( in long packet_size)

Description

This method sets the maximum size for the RTP packets in bytes. The value does not include the 4 bytes for the packet header.

Arguments
in long packet_size The requested maximum packet size.
Return Values

Success

OutOfRange

For introductory information, see Video Codec Objects.


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