The IG_mult_...() functions provide high level support for accessing the contents of multimedia files. These functions support two types of data: video (images associated with video or animation frames) and audio.

The IG_mult_open_...() functions are used to open a multimedia file and obtain a handle of ImageGear type HIGMULT. The file remains open and the handle remains valid until IG_mult_close() is used to close it. You must call IG_mult_close() when you're finished work.

You can determine the number of video frames in the file and the file's duration in milliseconds by calling IG_mult_duration_get(). If you're interested in whether or not the file contains video and/or audio data, you can call the functions IG_mult_has_video() and IG_mult_has_audio() to find out.

Video data is accessed on frame-by-frame basis. It is recommended to use the IG_mult_current_frame_...() functions, which keep track of the current frame you're accessing within the file. You can go back to the beginning of the file with IG_mult_current_frame_reset() and advance to the next frame with IG_mult_current_frame_advance(). You can seek to a specific time using IG_mult_current_frame_seek_time(), and seek to a specific frame number with IG_mult_current_frame_seek(). To determine if you've run off the end of the movie, use IG_mult_current_frame_is_valid().

There is a duration and an image associated with each frame. The duration specifies how long the frame should be displayed at a normal playback speed. To retrieve a frame's duration, use IG_mult_current_frame_duration_get(), or IG_mult_frame_duration_get() if you want to specify the frame number explicitly. A frame's duration is given in 100ns units. You can convert to milliseconds by dividing by 10000, but be aware that some common frame rates such as 29.97 frames per second (used in NTSC television) require the higher precision for correct playback speed. Also, depending on your application, you should not assume that all frames in a file have the same duration. To support a variable frame rate, as is common in animations but also possible in video clips, you must retrieve the duration of each individual frame.

To retrieve a frame's image, use IG_mult_current_frame_image_get(), or IG_mult_frame_image_get() if you want to specify the frame number explicitly. This will give you a HIGEAR image handle that can be used to access the image with all of ImageGear's functions that work on a HIGEAR. However, you should not attempt to modify the image or free it with IG_image_delete(). If you need to modify the image, use IG_image_duplicate() and work with the duplicate image. Remember to free the duplicate image when you're finished with it.

Audio data is accessed as blocks of uncompressed PCM audio samples. An audio sample represents the amplitude of an audio waveform at a particular point in time. Before you can retrieve audio data, you should find out what its format is by calling IG_mult_audio_format_get(). This will tell you the sample rate (number of samples per second), bits per sample, and number of channels. If the audio has multiple channels (i.e. stereo), the samples for each channel are stored in alternating order beginning with the left channel.

There is also a function to set the audio format: IG_mult_audio_format_set(). You can use this to request that ImageGear convert the file's audio format to your specified format as you retrieve audio data. Conversion may not be possible, so be sure to check the result when calling this function.

To retrieve audio data, use IG_mult_audio_get(). Provide a pointer to a buffer where it will copy the audio data to, as well as a pointer to a value containing the number of bytes of audio data to retrieve. If the call is successful, your buffer will contain audio data and the value you passed will contain the number of bytes of audio data that were copied. This number will be less than the number you requested if you requested more data than was available.

You can calculate the number of bytes of audio data to retrieve by using the audio format. Divide the number of bits per sample by 8 to get the number of bytes per sample. Then multiply by the number of channels. This gives the number of bytes needed to represent the audio at a single point in time. The number of bytes you request must be a multiple of this number. You can then multiply by the sample rate to expand out into time. For example, to calculate the number of bytes per second of audio:

Finally, there are some generalized functions for getting and setting parameters. These are the functions with "info" in the name. They can offer access to parameters which may be relevant to a whole file or an individual frame. These parameters may also be relevant to a particular file format or all file formats. These parameters are defined in accucnst.h. For more information about format-specific parameters, see the documentation for the formats supported by the IG_mult_...() functions.