iflMT(3) Image Format Library C++ Reference Manual iflMT(3)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;
Page 1
iflMT(3) Image Format Library C++ Reference Manual iflMT(3)
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.
Page 2
iflMT(3) Image Format Library C++ Reference Manual iflMT(3)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
Page 3
iflMT(3) Image Format Library C++ Reference Manual iflMT(3)
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
Page 4
iflMT(3) Image Format Library C++ Reference Manual iflMT(3)
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
Page 5
iflMT(3) Image Format Library C++ Reference Manual iflMT(3)
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
Page 6
iflMT(3) Image Format Library C++ Reference Manual iflMT(3)
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."
Page 7
iflMT(3) Image Format Library C++ Reference Manual iflMT(3)
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,
Page 8
