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

UMSMPEG1MovieFileReader Object

The UMSMPEG1MovieFileReader object provides the ability to read MPEG1 movie files. This object inherits or overrides all methods from the UMSMovieFileReader base class and adds one new method. The reader only supports access to one video stream and one audio stream at a time. The audio stream can be stereo. The video stream is decompressed to YUV420Plane images. There are no provisions for skipping frames or selecting reduced quality decompression. It is possible to seek to a frame number, but it is implemented by decompressing frames until the desired frame is reached. Because of these limitations the object has not been added to the UMS_config file.

The files can contain video and audio, video only, or audio only. If the file contains both video and audio then the audio is split into frames to match the video frame rate. If the file contains only audio then it is split into ten frames per second. This object does not support selecting audio tracks if the file has more than one track. This object does not support selecting video tracks if the file has more than one track. The most recent audio and video tracks encountered when the file is opened are used. This object does not support switching tracks in the middle of the file.

A YUV420Plane image is composed of three planes in memory. The pixels are in order from left to right, top to bottom. The first plane is the Y component, 8 bits per pixel. The second is the U component, 8 bits each. Each U corresponds to a 2x2 block of Y pixels. The third is the V component, 8 bits each. Each V corresponds to a 2x2 block of Y pixels.

For introductory information, see Formatted File Access Objects.

Method Descriptions

UMSMovieFileReader::ReturnCode open(in string file_name)

Description

Opens a movie file.

Arguments
in string file_name The name of the file to open.
Return Values
Success
Failure
OutOfMemory
UnsupportedFormat

UMSMovieFileReader::ReturnCode close()

Description

Closes the movie file.

Arguments

None.

Return Values
Success

UMSMovieFileReader::ReturnCode get_audio_bits_per_sample(inout long bits_per_sample)

Description

Returns the current bits-per-sample value for the selected audio track.

Arguments
inout long bits_per_sample The current bits-per-sample value for the selected audio track.
Return Values
Success
Failure
Uninitialized
NoAudio

UMSMovieFileReader::ReturnCode get_audio_format_type(out string audio_format_string)

Description

Returns the current audio format for the selected track. Storage for the string is allocated in the method. The caller must free the storage when the string is no longer needed.

Arguments
out string audio_format_string The returned audio format.
Return Values
Success
Failure
Uninitialized
NoAudio
OutOfMemory

UMSMovieFileReader::ReturnCode get_audio_frame(inout CompressedAudio audio_buffer, in long audio_track_id, in long frame_number)

Description

Returns the audio data for a specified frame and track.

Note: This object returns PCM audio data, not compressed audio data in the audio_buffer argument.
Arguments
inout CompressedAudio audio_buffer The location to place the audio data.
in long audio_track_id The track from which to get audio data. This object only accepts zero for this argument.
in long frame_number The number of the requested audio frame. The first frame in the file is presentation frame number zero.
Return Values
Success
Failure
Uninitialized
NoAudio
OutOfRange
InsufficientBufferLength
OutOfMemory
EndOfFile

UMSMovieFileReader::ReturnCode get_audio_number_of_channels(inout long audio_number_of_channels)

Description

Gives the current number of channels for the selected audio track.

Arguments
inout long audio_number_of_channels The number of channels. For example this value will be one for mono and two for stereo.
Return Values
Success
Failure
NoAudio
Uninitialized

UMSMovieFileReader::ReturnCode get_audio_samples_per_second(inout long samples_per_second)

Description

Returns the current samples per second for the selected audio track.

Arguments
inout long samples_per_second The audio sampling rate in units of samples per second.
Return Values
Success
Failure
NoAudio
Uninitialized

UMSMovieFileReader::ReturnCode get_audio_track(inout long audio_track_id)

Description

Returns the track number of the currently selected audio track.

Arguments
inout long audio_track_id The track id. This object always returns zero for this value.
Return Values
Success
Failure
NoAudio
Uninitialized

UMSMovieFileReader::ReturnCode get_current_frame_position(inout long presentation_frame_number)

Description

Returns the current frame position in the file.

Arguments
inout long presentation_frame_number The frame number of the data to be returned by the next call to the get_next_movie_frame method.
Return Values
Success
Failure
Uninitialized

UMSMovieFileReader::ReturnCode get_frame_rate(inout float frame_rate)

Description

Returns the video frame rate for the currently selected video track. If the file is audio only then it returns ten frames per second.

Arguments
inout float frame_rate The frame rate for the data in the file.
Return Values
Success
Failure
Uninitialized

UMSMovieFileReader::ReturnCode get_iframe_locations(in long ref_frame_num, inout long prev_iframe_num, inout long next_iframe_num, inout boolean is_iframe)

Description

Returns the frame positions of previous and next I-frames relative to a given video frame in the selected video track. This method is not implemented for this object.

Arguments
in long ref_frame_num The reference frame number from which to start looking. This value is not used by this object.
inout long prev_iframe_num The nearest I-frame with a smaller number than the reference frame. This value is not modified by this object.
inout long next_iframe_num The nearest I-frame with a larger number than the reference frame. This value is not modified by this object.
inout boolean is_iframe True if the reference frame is an I-frame. This value is not modified by this object.
Return Values
Failure
Uninitialized

UMSMovieFileReader::ReturnCode get_image_frame_dimensions(inout long width, inout long height)

Description

Returns the video frame dimensions for the currently selected video track.

Arguments
inout long width The width in pixels.
inout long height The height in pixels.
Return Values
Success
Failure
NoVideo
Uninitialized

UMSMovieFileReader::ReturnCode get_max_audio_buffer_size(inout long buffer_size)

Description

Returns the maximum buffer size required to hold any audio frame data for the currently selected audio track.

Arguments
inout long buffer_size The size in bytes needed to hold any audio frame.
Return Values
Success
Failure
NoAudio
Uninitialized

UMSMovieFileReader::ReturnCode get_max_video_buffer_size(inout long buffer_size)

Description

Returns the maximum buffer size required to hold any video frame data for the currently selected video track.

Arguments
inout long buffer_size The size in bytes needed to hold any video frame.
Return Values
Success
Failure
NoVideo
Uninitialized

UMSMovieFileReader::ReturnCode get_movie_length(inout long number_of_frames)

Description

Returns the number of frames in the currently selected video track. This method will usually return -1 indicating that the object is not able to determine how many video frames are in the file. This method will return zero if the file is audio-only.

Arguments
inout long number_of_frames Either contains the number of video frames in the file or -1.
Return Values
Success
Failure
Uninitialized

UMSMovieFileReader::ReturnCode get_next_movie_frame(inout CompressedAudio audio_buffer, inout CompressedVideo video_buffer, inout long presentation_frame_number)

Description

Returns the audio and video data for the next frame.

Note: This object returns PCM audio data, not compressed audio data in the audio_buffer argument. This object returns YUV420Plane data, not compressed video data in the video_buffer argument.
Arguments
inout CompressedAudio audio_buffer The location to place the audio data. If the file contains no audio the audio_buffer length will be set to zero.
inout CompressedVideo video_buffer The location to place the video data. If the file contains no video the video_buffer length will be set to zero.
inout long presentation_frame_number The presentation frame number of the video and audio data. The first frame in the file is presentation frame number zero.
Return Values
Success
Failure
Uninitialized
InsufficientBufferLength
OutOfMemory
EndOfFile

UMSMovieFileReader::ReturnCode get_number_of_audio_tracks(inout long number_of_audio_tracks)

Description

Returns the number of audio tracks contained in the file. This object does not support selecting audio tracks if the file has more than one track. The most recent track encountered when the file is opened is used.

Arguments
inout long number_of_audio_tracks The number of audio tracks. This object returns either one or zero.
Return Values
Success
Failure
Uninitialized

UMSMovieFileReader::ReturnCode get_number_of_video_tracks(inout long number_video_tracks)

Description

Returns the number of video tracks contained in the file. This object does not support selecting video tracks if the file has more than one track. The most recent track encountered when the file is opened is used.

Arguments
inout long number_of_video_tracks The number of video tracks. This object returns either one or zero.
Return Values
Success
Failure
Uninitialized

UMSMovieFileReader::ReturnCode get_video_aspect_ratio(inout float video_aspect_ratio)

Description

Returns the video aspect ratio for the currently selected video track.

Arguments
inout float video_aspect_ratio The video aspect ratio. This object always returns 1.0.
Return Values
Success
Failure
Uninitialized

UMSMovieFileReader::ReturnCode get_video_format_type(out string video_format_string)

Description

Returns the format of the selected video track. Storage for the string is allocated in the method. The caller must free the storage when the string is no longer needed.

Arguments
out string video_format_string The returned format string. This object always returns "YUV420Plane".
Return Values
Success
Failure
NoVideo
Uninitialized
OutOfMemory

UMSMovieFileReader::ReturnCode get_video_frame(inout CompressedVideo video_buffer, in long video_track_id, in long frame_number)

Description

Returns the video data for a specified frame and track.

Note: This object returns YUV420Plane data, not compressed video data in the video_buffer argument.
Arguments
inout CompressedVideo video_buffer The location to place the video data.
in long video_track_id The track from which to get video data. This object only accepts zero for this argument.
in long frame_number The number of the requested video frame. The first frame in the file is presentation frame number zero.
Return Values
Success
Failure
Uninitialized
NoVideo
OutOfRange
InsufficientBufferLength
OutOfMemory
EndOfFile

UMSMovieFileReader::ReturnCode get_video_frame_type(inout VideoFrameType video_frame_type)

Description

Indicates the type of video frames in the file. The types can be I-frames, delta frames, and bidirectional delta frames.

Arguments
inout VideoFrameType video_frame_type This object always returns UMSMovieFileReader_IFrame.
Return Values
Success
Failure
NoVideo
Uninitialized

UMSMovieFileReader::ReturnCode get_video_track(inout long video_track_id)

Description

Returns the track number of the currently selected video track.

Arguments
inout long video_track_id The track id. This object always returns zero for this value.
Return Values
Success
Failure
NoVideo
Uninitialized

UMSMovieFileReader::ReturnCode seek_to_frame(in long frame_number)

Description

Seeks to a given frame location within the selected tracks. This method is implemented by decompressing frames until the desired frame is reached.

Arguments
in long frame_number The desired presentation frame number. The first frame in the file is presentation frame number zero.
Return Values
Success
Failure
Uninitialized
OutOfMemory
EndOfFile

UMSMovieFileReader::ReturnCode set_audio_track(in long audio_track_id)

Description

Selects an audio track number.

Arguments
in long audio_track_id The desired audio track. This object accepts only zero.
Return Values
Success
Failure
NoAudio
Uninitialized

UMSMovieFileReader::ReturnCode set_speed_factor(in unsigned long percent)

Description

Specifies a playback speed factor.

Arguments
in unsigned long percent The desired speed factor. This object accepts only 100.
Return Values
Success
Failure
Uninitialized

UMSMovieFileReader::ReturnCode set_video_track(in long video_track_id)

Description

Selects a video track number.

Arguments
in long video_track_id The desired video track. This object accepts only zero.
Return Values
Success
Failure
NoVideo
Uninitialized

UMSMovieFileReader::ReturnCode get_audio_number_format(out string number_format)

Description

Returns the number format of the selected audio track. Storage for the string is allocated in the method. The caller must free the storage when the string is no longer needed.

Arguments
out string number_format The returned number format string. This object always returns "TWOS_COMPLEMENT".
Return Values
Success
Failure
NoAudio
Uninitialized
OutOfMemory

UMSMovieFileReader::ReturnCode get_audio_byte_order(out string byte_order)

Description

Returns the byte order of the selected audio track. Storage for the string is allocated in the method. The caller must free the storage when the string is no longer needed.

Arguments
out string byte_order The returned byte order string.
Return Values
Success
Failure
NoAudio
Uninitialized
OutOfMemory

UMSMovieFileReader::ReturnCode open_with_frw(in UMSFileReadWrite frw)

Description

This method is new with this object and is not inherited or overridden from the UMSMovieFileReader base class. This method is an alternative to the open method. The open_with_frw and open methods should not be used at the same time. It accepts an object of class UMSFileReadWrite and uses it for all file operations. The UMSFileReadWrite object should be in the open state at the time of this method call. The passed-in object is not freed when the UMSMPEG1MovieFileReader object is closed. The UMSFileReadWrite object need not have the lseek method implemented. If it returns an error the UMSMPEG1MovieFileReader object will assume that the input data is a non-seekable stream of data.

Arguments
in UMSFileReadWrite frw An object to be used for all file operations. It should be in the open state at the time of the method call.
Return Values
Failure
OutOfMemory
UnsupportedFormat
Success

For introductory information, see Formatted File Access Objects.

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