iflMT(3)
iflMT, iflQT, iflMV - a multi-track movie file
As shipped in IRIX 6.5.5. Unchanged since IRIX 6.5.
NAME iflMT, iflQT, iflMV - a multi-track movie file HEADER FILE #include <ifl/iflMT.h> DESCRIPTION Movie files consist of image and audio data, which are stored in parallel tracks. A movie file may consist of multiple tracks of data, and each track may contain either image or audio information. A movie file's multi-track structure is very useful in multi-media applications where visual output in one track has to be synchronized with audio output in another. This structure, which allows related data to be grouped together while remaining in separate and distinct tracks, makes movie files a logical storage format for confocal microscopes. In many cases, users of confocal microscopes examine a single sample at multiple wavelengths; it only makes sense to store data generated from these separate channels (or "labels") in different image tracks. About Multi-track file objects. The Image Format Library does not support the concept of "tracks": IFL assumes that all datafiles consist of a single track of data laid out in sequential fashion. For image files containing multi-track data, this causes two problems: 1. IFL does not provide any generic mechanism to switch between different tracks in a single image file. Fortunately, IFL provides a way around this: the iflFile base class (which defines the core functionality of all IFL file objects) includes "getTag" and "setTag" methods that can be used to fetch and modify various attributes of an image file. Both the QuickTime and SGI derived objects provide extensions to these methods that allow applications to change the current track that is operated upon. 2. Since the IFL cache has no notion of multiple tracks of image data, it will get hopelessly confused if an application changes the image track currently being operated on. For example, suppose an application read frames 0, 1, and 2 from track #0 into the IFL caches, then changes the current track to track #1. Clearly, we need to load frames 0, 1, and 2 again, since we are dealing with a different track of image; as far as the IFL cache is concerned, however, there is no need to reload images 0, 1, and 2 of track #1, as they are already resident in memory; The user MUST flush the IFL cache whenever it is changed. Since the iflFile object (which is the base class of iflMTFile object) is not derived from the ilCacheImg class, it cannot automatically flush the cache for the user. The user application flushes the cache by calling the "flush" method of the ilFileImg object as follows: ilFileImg *fileImage; fileImage->flush(TRUE); Fun Facts 1. QuickTime and Movie files support only one compression mode each for write operations (read operations seem to be able to recognize more.) Quicktime supports iflPACKBITS, and SGI supports iflSGIRLE. Both modes support iflNoCompression. 2. I have only tested this code for reading and writing image files with sequential pixel ordering (i.e. iflSequential.) I have no idea how it will behave with iflSeparate pixel ordering (where the pixel components are stored on separate planes.) Since the vast majority of movie files use sequential pixel ordering, this shouldn't be a problem. 3. Deleting a frame or a track from a movie file does NOT result in the automatic release of the disk storage space used by that frame or track; deleted frames and tracks remain in the movie file as a place-holder. Users should use the iflMToptimizeMovie extension to the setTag method to force the movie file to release the unused space taken up by deleted frames or tracks. 4. The "correct" way to insert a new image to a file in IFL is to call the "appendImg" method. AppendImg is used by the iflMTFile object to create a space holder image, which is later written over by the object's setPage method. Since the place holder is always deleted, the resulting file will always have to be optimized, which is a very time-consuming process. As described above, deleting an image does not free up the its disk space. This method of appending images is not very efficient. As an alternative, an extension has been provided that allows the application to create an image and write to it in one step. This extension is called iflMTinsertFrame, and is invoked using the "setTag" method. As long as no frames or tracks are deleted, movie files created this way do not need to be optimized. Multi-track support Setting multi-track attributes using setTag() The following operations extend the generic IFL setTag mechanism to support multi-track movie files, allowing a user to select a single track, set movie, track and image (in QuickTime files) parameters, append a track, remove a track, and optimize the movie file. The prototype of the setTag method is: iflStatus iflQTFile::setTag(int tag, va_list ap); input : tag - token identifying the type of item to be set. ap - variable list containing items to be set. The tag parameter identifies the operation to be performed, and the variable list contains the parameters required by the specified operation. Since the contents of the variable list are NOT checked, the application programmer must be VERY careful to pass the correct values, the correct TYPE of values, and the correct NUMBER of values in the correct order. The following list describes the extensions available using the ifl setTag mechanism. tag: iflMTsetFrameTaggedParam description: inserts the string pointed to by "tag_data" into the the parameter list of the current frame. The string is referenced by the name string pointed to by "tag_name". parameter 1: char* tag_name parameter 2: char* tag_data tag: iflMTsetFrameAllParams description: inserts an array of strings pointed to by "tags" into the parameter list of the current frame. These strings are referenced by name strings contained in the string array pointed to by "labels". Both the tags and labels arrays contain the number of strings specified by the "number_of_strings" parameter; there is a one-to-one correspondence between the data strings in the "tags" array and the name strings in the "labels" array. parameter 1: int number_of_strings parameter 2: char** labels parameter 3: char** tags tag: iflMTsetMovieHeaderTaggedParam description: inserts the string pointed to by "tag_data" into the the parameter list of the movie. The string is referenced by the name string pointed to by "tag_name". parameter 1: char* tag_name parameter 2: char* tag_data tag: iflMTsetMovieHeaderAllParams description: inserts an array of strings pointed to by "tags" into the parameter list of the movie. These strings are referenced by name strings contained in the string array pointed to by "labels". Both the tags and labels arrays contain the number of strings specified by the "number_of_strings" parameter; there is a one-to-one correspondence between the data strings in the "tags" array and the name strings in the "labels" array. parameter 1: int number_of_strings parameter 2: char** labels parameter 3: char** tags tag: iflMTsetTrackHeaderTaggedParam description: inserts the string pointed to by "tag_data" into the the parameter list of the track. The string is referenced by the name string pointed to by "tag_name". parameter 1: char* tag_name parameter 2: char* tag_data tag: iflMTsetTrackHeaderAllParams description: inserts an array of strings pointed to by "tags" into the parameter list of the track. These strings are referenced by name strings contained in the string array pointed to by "labels". Both the tags and labels arrays contain the number of strings specified by the "number_of_strings" parameter; there is a one-to-one correspondence between the data strings in the "tags" array and the name strings in the "labels" array. parameter 1: int number_of_strings parameter 2: char** labels parameter 3: char** tags tag: iflMTappendImageTrack description: appends a new image track to the movie at the current track index; all following tracks are bumped one position. parameter 1: int xSize parameter 2: int ySize parameter 3: iflColorModel colorModel parameter 4: iflOrientation orientation parameter 5: iflCompression compression tag: iflMTappendAudioTrack description: appends a new audio frame to the current track at the current index; all following frames are bumped one posiion. This extension assumes that the current track is an audio track. parameter 1: int bitsPerSample parameter 2: double samplingRate tag: iflMTremoveCurrentTrack description: removes the current track from the movie. No parameters. tag: iflMTsetCurrentTrack description: selects the current track of the movie file. This track may be either an audio or an image track. parameter 1: int index tag: iflMTsetImageTrack description: selects an image track to be the current track. parameter 1: int index tag: iflMTsetAudioTrack description: selects an audio track to be the current track. parameter 1: int index tag: iflMTinsertFrame description: inserts an image frame into the current track at the current frame index. This extension assumes that the current track is an image track. parameter 1: void* ptr parameter 2: int length tag: iflMTremoveFrame description: deletes the current frame from the current track. No parameters. tag: iflMToptimizeMovie description: cleans up the movie file, removing all deleted images from the movie file. Fetching multi-track attributes using getTag() The following operations extend the generic IFL "getTag" mechanism to support multi-track movie files, allowing a user to determine the state of the multi-track file. Using "getTag", an application can query the current track; read movie, track and image (for QuickTime files) parameters; determine the frame height and width; and query the track medium. The prototype of the getTag method is: iflStatus iflQTFile::getTag(int tag, va_list ap) input : tag - token identifying the type of item to be read. ap - variable list containing items to be read. The tag parameter identifies the operation to be performed, and the variable list contains the parameters required by the specified operation. Since the contents of the variable list are NOT checked, the application programmer must be VERY careful to pass the correct values, the correct TYPE of values, and the correct NUMBER of values in the correct order. The following list describes the extensions available using the ifl getTag mechanism. tag: iflMTgetFrameTaggedParam description: retrieves the data string referred to by the name string pointed by "tag_name" from the parameter list of the current image frame. This data string is placed into the string pointed to by "tag_data". The maximum length of the "tag_data string is contained in "dst_length". parameter 1: char* tag_name parameter 2: int dst_length parameter 3: char* tag_data tag: iflMTgetFrameAllParams description: retrieves the data strings referred to by the name strings stored in "labels" from the parameter list of the current image frame. These data strings are stored in the string array "tags". The maximum length of all strings stored in "tags" is stored in "max_string_length", and the number of strings stored in both "labels" and "tags" is contained in "number_of_strings". There is a one-to-one correspondence between the name strings stored in "labels" and the data strings stored in "tags". parameter 1: int number_of_strings parameter 2: char** labels parameter 3: char** tags parameter 4: int max_string_length tag: iflMTgetTrackHeaderTaggedParam description: retrieves the data string referred to by the name string pointed by "tag_name" from the parameter list of the current track. This data string is placed into the string pointed to by "tag_data". The maximum length of the "tag_data string is contained in "dst_length". parameter 1: char* tag_name parameter 2: int dst_length parameter 3: char* tag_data tag: iflMTgetTrackHeaderAllParams description: retrieves the data strings referred to by the name strings stored in "labels" from the parameter list of the current track. These data strings are stored in the string array "tags". The maximum length of all strings stored in "tags" is stored in "max_string_length", and the number of strings stored in both "labels" and "tags" is contained in "number_of_strings". There is a one-to-one correspondence between the name strings stored in "labels" and the data strings stored in "tags". parameter 1: int number_of_strings parameter 2: char** labels parameter 3: char** tags parameter 4: int max_string_length tag: iflMTgetMovieHeaderTaggedParam description: retrieves the data string referred to by the name string pointed by "tag_name" from the parameter list of the movie. This data string is placed into the string pointed to by "tag_data". The maximum length of the "tag_data string is contained in "dst_length". parameter 1: char* tag_name parameter 2: int max_string_length parameter 3: char* tag_data tag: iflMTgetMovieHeaderAllParams description: retrieves the data strings referred to by the name strings stored in "labels" from the parameter list of the movie. These data strings are stored in the string array "tags". The maximum length of all strings stored in "tags" is stored in "max_string_length", and the number of strings stored in both "labels" and "tags" is contained in "number_of_strings". There is a one-to-one correspondence between the name strings stored in "labels" and the data strings stored in "tags". parameter 1: int number_of_strings parameter 2: char** labels parameter 3: char** tags parameter 4: int max_string_length tag: iflMTgetNumberOfTracks description: retrieves the number of tracks in the movie and places it in the location pointed to by "number_of_tracks." parameter 1: int* number_of_tracks tag: iflMTgetNumberOfFramesInTrack description: retrieves the number of frames in the current track and places it in the location pointed to by "number_of_frames". parameter 1: int* number_of_frames tag: iflMTgetFrameHeight description: retrieves the number of pixels in the vertical dimension in the current frame and places it in the location pointed to by "height". parameter 1: int* height tag: iflMTgetFrameWidth description: retrieves the number of pixels in the horizontal dimension in the current frame and places it in the location pointed to by "height". parameter 1: int* width tag: iflMTgetNumberOfAudioTracks description: retrieves the number of audio tracks in the movie and places it in the location pointed to by "number_of_audio_tracks". parameter 1: int* number_of_audio_tracks tag: iflMTgetNumberOfImageTracks description: retrieves the number of image tracks in the movie and places it in the location pointed to by "number_of_image_tracks". parameter 1: int* number_of_image_tracks tag: iflMTgetTrackMedium description: determines the type of medium stored in the current track and places it in the location pointed to by "track_medium". parameter 1: int* track_medium Returns: if iflOKAY => tagged data successfully read from Movie frame. else => error reading tagged data from Movie frame. SEE ALSO iflFile, ilFileImg,