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

UMSH263Encoder Object

The UMSH263Encoder object provides methods to compress video frames to the H.263 video format.

To learn more about the UMSH263Encoder 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 not supported
   OutOfRange, // Bad parameter value 
   Uninitialized, // Uninitialized internal state variable 
   OutOfMemory, // Failure allocating internal memory
   UnsupportedValue, // Parameter value not supported
   ModeNotSupported // Requested mode not supported
   };
enum ImageFormatIn { 
   YUVPlanar, // YUV 4:2:0 planar (Y plane, U plane, V plane)
   YUV422, // YUV 4:2:2 interleaved format 
   RGB24, // 32-bits per pixel; pixel is 0RGB 
   BGR24 // 32-bits per pixel; pixel is 0BGR 
   };
enum FrameType { 
   FIRST, // First frame of the sequence
   INTER, // Inter-frame 
   INTRA // Intra-frame 
   };
enum FrameRate { 
   R_3, // Target rate of 3 frames per second
   R_5, // Target rate of 5 frames per second 
   R_10, // Target rate of 10 frames per second 
   R_15, // Target rate of 15 frames per second 
   R_30 // Target rate of 30 frames per second 
   };
enum RateControl { 
   ON, // Enable bit rate control 
   OFF // Disable bit rate control 
   };
enum PBFrameMode { 
   PB_ON, // Enable PB Frame mode 
   PB_OFF // Disable PB Frame mode
   }; 
enum UnrestrictedMVMode { 
   MV_ON, // Enable unrestricted motion vector range
   MV_OFF // Disable unrestricted motion vector range
   }; 
enum ArithmeticCodingMode { 
   AC_ON, // Enable arithmetic coding
   AC_OFF // Disable arithmetic coding 
   }; 
enum AdvancedPredictionMode { 
   AP_ON, // Enable advanced prediction
   AP_OFF // Disable advanced prediction 
   }; 
enum PacketMode { 
   ModeA, // RTP 263 Payload Mode A
   ModeB, // RTP 263 Payload Mode B 
   ModeC // RTP 263 Payload Mode C 
   };
enum ImageSize { 
   SQCIF, // 128 x 96 pixels
   QCIF, // 176 x 144 pixels
   CIF, // 352 x 288 pixels 
   CIF_4, // 704 x 576 pixels 
   CIF_16 // 1408 x 1152 pixels 
   };

Method Definitions

ReturnCode set_image_format(in ImageFormatIn image_format )

Description

Set the input image format. The options are YUVPlanar, YUV422, PadRGB24 and PadBGR24.

Arguments
in ImageFormatIn image_format The input image format of the data to be compressed.
Return Values

Success

Failure

ReturnCode get_image_format(inout ImageFormatIn image_format )

Description

Get the input image format setting.

Arguments
inout ImageFormatIn image_format A pointer to the ImageFormatIn variable to hold the current setting for the input image format.
Return Values

Success

InvalidArgument

ReturnCode set_image_size(in long width; in long height)

Description

Set the input image dimensions. Currently, only SubQCIF, QCIF, and CIF are supported.

Arguments
in long width The width in pixels.
in long height The height in pixels.
Return Values

Success

Failure

OutOfRange

ReturnCode get_image_size(inout long width, inout long height )

Description

Get the current input image dimensions.

Arguments
inout long width A pointer to the width in pixels.
inout long height A pointer to the height in pixels.
Return Values

Success

InvalidArgument

ReturnCode set_packet_size(in long packet_size )

Description

The encoder can, when packet_size is set to a non-zero value, partition the compressed frames into chunks that may be sent as a series of packets. This method sets the maximum size of the packets. This feature is turned off by setting the size value to zero.

Arguments
in long packet_size A long variable that specifies the packet size in bytes.
Return Values

Success

Failure

OutOfRange

ReturnCode get_packet_size( inout long packet_size)

Description

Get the packet size setting. If this value is zero (default), then the encoder does not determine packet boundaries.

Arguments
inout long packet_size A pointer to the long variable to hold the current setting for the packet size.
Return Values

Success

InvalidArgument

ReturnCode set_frame_rate(in FrameRate frame_rate )

Description

Set the target frame rate. The target frame and the bit_rate are used by the encoder for rate control. The target frame rate is a maximum rate that the encoder attempts to achieve, while staying at or below the target bit rate.

Arguments
in FrameRate frame_rate An enum variable that specifies the target frame rate.
Return Values

Success

Failure

ReturnCode get_frame_rate(inout FrameRate frame_rate )

Description

Get the current input frame rate setting.

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

Success

InvalidArgument

ReturnCode set_rc_state(in RateControl rc_state )

Description

Enable or disable the bit rate control. If rate control is turned off, the bit rate setting is ignored.

Arguments
in RateControl rc_state An enum variable that enables or disables the rate control.
Return Values

Success

Failure

ReturnCode get_rc_state(inout RateControl rc_state )

Description

Get the setting of the rate control state.

Arguments
inout RateControl rc_state A pointer to an enum variable to hold the current setting for the rate control state.
Return Values

Success

InvalidArgument

ReturnCode set_bits_per_second(in long bits_per_second )

Description

Set the average bit rate, in bits per second, for the compressed data stream.

Arguments
in long bits_per_second A long variable that sets the average bit rate for the compressed data stream.
Return Values

Success

Failure

ReturnCode get_bits_per_second(inout long bits_per_second )

Description

Get the current setting for the compressed data rate.

Arguments
inout long bits_per_second A pointer to a long variable to hold the current setting for the bit rate.
Return Values

Success

InvalidArgument

ReturnCode set_motion_displacement(inout long displacement )

Description

Set the maximum motion displacement, in unit of pixels. The maximum setting is 31.

Arguments
inout long displacement A pointer to a long variable that sets the maximum pixel displacement used in the motion vector search algorithm.
Return Values

Success

Failure

ReturnCode get_motion_displacement(inout long displacement )

Description

Get the current setting for the maximum motion displacement.

Arguments
inout long displacement A pointer to a long variable to hold the current setting for the motion displacement.
Return Values

Success

InvalidArgument

ReturnCode set_max_quantization(inout long max_quantization_value )

Description

Set the maximum quantization value. A larger number indicates a bigger step size and lower image quality. This value is a maximum possible value; the actual values used may be lower depending on the image content and bit rate setting.

Arguments
inout long max_quantization_value A pointer to a long variable that sets the maximum quantization value used by the encoder.
Return Values

Success

Failure

ReturnCode get_max_quantization(inout long max_quantization_value )

Description

Get the current setting for the maximum image quantization.

Arguments
inout long max_quantization_value A pointer to a long variable to query the current setting for the maximum quantization value.
Return Values

Success

InvalidArgument

ReturnCode set_encoder_mode(in PBFrameMode frame_mode, in UnrestrictedMVMode mv_mode, in ArithmeticCodingMode coding_mode, in AdvancedPredictionMode ap_mode )

Description

Enable one or more of the advanced encoder modes. Currently none of these advanced modes are supported.

Arguments
in PBFrameMode frame_mode Set the encoder mode to generate PB frames (not supported).
in UnrestrictedMVMode mv_mode Set the encoder mode to use unrestricted motion vectors (not supported).
in ArithmeticCodingMode coding_mode Set the encoder mode to use arthimetic coding (not supported).
in AdvancedPredictionMode ap_mode Set the encoder mode to advanced prediction mode (not supported).
Return Values

Success

Failure

ReturnCode get_encoder_mode(inout PBFrameMode frame_mode, inout UnrestrictedMVMode mv_mode, inout ArithmeticCodingMode coding_mode, inout AdvancedPredictionMode ap_mode )

Description

Get the current advanced mode setting.

Arguments
inout PBFrameMode frame_mode A pointer to the enum type variable PBFrameMode (ON or OFF).
inout UnrestrictedMVMode mv_mode A pointer to the enum type variable UnrestrictedMVMode (ON or OFF).
inout ArithmeticCodingMode coding_mode A pointer to the enum type variable ArithmeticCodingMode (ON or OFF).
inout AdvancedPredictionMode ap_mode A pointer to the enum type variable AdvancedPredictionMode (ON or OFF).
Return Values

Success

InvalidArgument

ReturnCode get_max_buffer_size(inout long buffer_size )

Description

Get the maximum compressed buffer size for the current input image size, in bytes.

Arguments
inout long buffer_size A pointer to a long variable to query the maximum output buffer size needed for a compressed frame.
Return Values

Success

InvalidArgument

ReturnCode set_packet_mode(in PacketMode packet_mode )

Description

Enable the appropriate RTP Payload type. Currently only payload mode A is supported.

Arguments
in PacketMode packet_mode An enum variable that specifies the H.263 payload mode.
Return Values

Success

Failure

ReturnCode get_packet_mode(inout PacketMode packet_mode )

Description

Query the current setting for the RTP payload mode.

Arguments
inout PacketMode packet_mode A pointer to an enum variable that holds the payload mode.
Return Values

Success

InvalidArgument

ReturnCode get_packet_info(inout long first_header_word, inout long second_header_word, inout long third_header_word, inout long start_offset, inout long packet_length )

Description

Read packet information until packet length equals zero. This method must be called after compress_frame and all information must be read before next call to compress_frame.

Arguments
inout long first_header_word A pointer to a long variable that holds the first header value.
inout long second_header_word A pointer to a long variable that holds the second header value.
inout long third_header_word A pointer to a long variable that holds the third header value.
inout long start_offset A pointer to a long variable to query the next starting packet offset, in bytes, within the compressed data buffer.
inout long packet_length A pointer to a long variable to query the packet length, in bytes, for the next RTP packet.
Return Values

Success

InvalidArgument

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

Description

Compress the input image frame to a compressed frame, either I-frame (type setting INTRA), P-frame (type setting INTER), or if advanced PB frame is set, a PB-frame (type setting INTER).

The frame_incr value returned by the encoder informs the application how many input image frames should be skipped before calling the compress_frame method again. The frame_incr value only needs to be checked if rate control is ON.

Arguments
in ImageFrame image_frame A pointer to a SOM sequence structure that holds the current input frame.
inout CompressedFrame comp_frame A pointer to a SOM sequence structure to hold the compressed frame.
in FrameType frame_type An enum variable that specifies the type of frame to create: INTRA (I-frame), INTER (P-frame), or PBFrame (not supported).
inout long frame_incr A pointer to a long variable to query the frame offset. If set by the application, and passed into the object, it specifies the offset for the current frame, relative to the last compressed frame. If set by the UMSH263Encoder object, and read by the application, it specifies the offset to the next frame to be compressed, relative to the currently compressed frame.
Return Values

Success

Failure

InvalidArgument

For introductory information, see Video Codec Objects.


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