Concepts Common to Video Codec Objects

Ultimedia Services Version 2 for AIX: Programmer's Guide and Reference

Concepts Common to Video Codec Objects

To learn more about the common features of video codec objects, see:

For introductory information, see Programming with Video Codec Objects.

Method Calls

Common method calls for decoders include:

set_image_format	Selects the format of the frames at the output of a decoder object. A particular decoder object might only support a subset of the complete list of formats; the method returns an error code if the requested image format is unsupported or invalid.
set_image_size	Sets the size of the output frames of a decoder object. The calling application should be able to obtain these from the file that contains the compressed image or video. Note that a particular decoder might only support certain frame sizes.
set_colormap_attributes	Used for the RGB8Dither format. Sets the size of the decoder's color map and the position to which it is copied (after formatting) in the color map of the display window. The method uses the requested size of the color map to select from the sizes a particular decoder supports.
get_color_map	Copies the decoder's internal copy of its color map to an area provided by the calling application. Each entry in the color map consists of 4 bytes: 0, red, green, and blue. The application provides a pointer to an area of memory to receive the color map.
decompress_frame	Decompresses one frame of video and formats it according to the selected image format. The application provides pointers to the compressed frame and an area of memory to receive the decompressed frame. If the compressed video has reference frames and delta frames, the application should start the decoding at an reference frame.

Common method calls for encoders include:

set_image_format	Sets the format of the frames that an encoder object accepts at its input. All the encoders support the RGB24 format, but none support RGB8Dither.
set_image_size	Sets the dimensions of the input frames that the encoder expects.
set_subimage_size	Specifies a rectangular subimage of an input frame that is actually encoded. The method specifies the dimensions of the subimage and its position in the input frame. It allows the application to select an area of interest or to conserve CPU power.
get_max_buffer_size	Returns a size for a buffer that is virtually guaranteed to be large enough to hold a compressed frame. The size given depends on the size of the frames or subimages that are encoded. With most encoders, it is impossible to guarantee that the buffer size is always sufficient, but the probability of overrun is extremely small.
compress_frame	Compresses one frame or subimage. The calling application provides pointers to the input frame and the buffer to receive the compressed frame.

Object Behavior and Buffering

Object behavior and buffering are determined by methods. For example, the set_image_format, set_image_size, and get_color_map methods are used to set up objects for operation; the compress_frame and decompress_frame methods cause the objects to process and transfer image data.

Applications and objects communicate to achieve a task. For example, in a decoding operation, an object gets data from a compressed frame within an application, the object decodes the data, and the object sends an image frame back to the application.

Tips for Using Video Codecs

The following tips provide important information for using decoders:

To get a list of the image formats supported by a particular decoder, call get_image_formats. This method returns a list of strings; each string is the name of an image format.
For image formats other than RGB8Dither, call set_image_format and set_image_size in either order and allocate memory for the compressed and decoded frames. Then, call decompress_frame to decompress each frame.
For the image format RGB8Dither, call set_image_format, set_image_size, and set_colormap_attributes in any order. After calling set_colormap_attributes, use the values of the color map size and colormap index returned by set_colormap_attributes. Then, allocate memory for the color map and call get_color_map to get the decoder's color map. Format this and insert it into the color map of the display window. Then, allocate memory for the compressed and decoded frames. Finally, call decompress_frame to decompress each frame.
Optionally, call set_display_size to set the dimensions of the video frames at the output of the decoder independently of the native dimensions of the compressed frames. This method can be called at any time. This method works only for RGB formats.
If the set_display_size method is not called, or if it is called with both dimensions equal to 0, the dimensions of each decoded frame are the original dimensions of the compressed frames.
The method get_max_output_buffer_size returns the size of the output buffer needed to receive the decoded frames for a particular image format and a given frame size.
Generally, a decoder has a few real quality levels. Therefore, the set_output_quality method returns the actual quality level via the output_quality_factor parameter. If the particular decoder has only one quality level, the method always returns a value of 100.
To skip a frame, call the decompress_frame method with the skip_flag parameter set to 1; the decoder updates its internal state, but it does not produce a formatted output frame.
For normal decoding, set skip_flag to 0.

The following tips provide important information for using encoders:

To encode complete frames, call set_image_format and set_image_size in either order, and call get_max_buffer_size. Then, allocate memory forthe output buffer of the compressed frames. Call compress_frame to compress each frame.
To limit the area of each frame that is encoded, call set_subimage_size just after the call to set_image_size.
All encoders support the PadRGB24 format, and most support a YUV format; none support the RGB8Dither format.

The following tip provides important information for using buffers:

The numbers of bytes occupied by a frame of dimensions FrameWidth x FrameHeight in some of the formats are:

RGB8Dither	FrameWidth x FrameHeight
YUV9	(9/8) x FrameWidth x FrameHeight
YVU9	(9/8) x FrameWidth x FrameHeight
YUV420	(3/2) x FrameWidth x FrameHeight
YUV422	2 x FrameWidth x FrameHeight
PadRGB24	4 x FrameWidth x FrameHeight
Mono	FrameWidth x FrameHeight
PadBGR24Reverse	4 x FrameWidth x FrameHeight

For introductory information, see Programming with Video Codec Objects.