Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

New Functions, Data Types, and Constants in QuickTime 7

This chapter describes all the new QuickTime functions, data structures, constants, and callbacks available in this software release.

If you are a QuickTime API-level developer, content author, multimedia producer or Webmaster who is currently working with QuickTime, you should read this chapter and use it for reference, as needed, in your application development.

QuickTime 7 API Reference

The following functions, callbacks, structures, and constants are new or changed with this release of QuickTime.

Functions

Functions that are new in QuickTime 7 are described in this section; they are listed in alphabetical order.

AddMediaSample2

Adds sample data and a description to a media.

OSErr AddMediaSample2 (
   Media                      theMedia,
   const UInt8                *dataIn,
   ByteCount                  size,
   TimeValue64                decodeDurationPerSample,
   TimeValue64                displayOffset,
   SampleDescriptionHandle    sampleDescriptionH,
   ItemCount                  numberOfSamples,
   MediaSampleFlags           sampleFlags,
   TimeValue64                *sampleDecodeTimeOut );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

dataIn

A handle to the sample data. The function adds this data to the media specified by theMedia. You specify the number of bytes of sample data with the size parameter.

size

The number of bytes of sample data to be added to the media. This parameter indicates the total number of bytes in the sample data to be added to the media, not the number of bytes per sample. Use the numberOfSamples parameter to indicate the number of samples that are contained in the sample data.

decodeDurationPerSample

The duration of each sample to be added, representing the amount of time that passes while the sample data is being displayed. You must specify this parameter in the media’s time scale. For example, if you are adding sound that was sampled at 22 kHz to a media that contains a sound track with the same time scale, you would set durationPerSample to 1. Similarly, if you are adding video that was recorded at 10 frames per second to a video media that has a time scale of 600, you would set this parameter to 60. Note that this is the duration per sample, regardless of the number of samples being added.

displayOffset

A 64-bit time value that specifies the offset between the decode time (the start time of the track plus the duration of all previous samples) and the display time. This value is normally zero unless the sample is frame reordering compressed video.

sampleDescriptionH

A handle to a SampleDescription structure. Some media structures may require sample descriptions. There are different descriptions for different types of samples. For example, a media that contains compressed video requires that you supply an ImageDescription structure. A media that contains sound requires that you supply a SoundDescription structure. If the media does not require a SampleDescription structure, set this parameter to NIL.

numberOfSamples

The number of samples contained in the sample data to be added to the media. The Movie Toolbox considers the value of this parameter as well as the value of the size parameter when it determines the size of each sample that it adds to the media. You should set the value of this parameter so that the resulting sample size represents a reasonable compromise between total data retrieval time and the overhead associated with input and output. You should also consider the speed of the data storage device; CD-ROM devices are much slower than hard disks, for example, and should therefore have a smaller sample size. For a video media, set a sample size that corresponds to the size of a frame. For a sound media, choose a number of samples that corresponds to between 0.5 and 1.0 seconds of sound. In general, you should not create groups of sound samples that are less than 2 KB in size or greater than 15 KB. Typically, a sample size of about 8 KB is reasonable for most storage devices.

sampleFlags

Flags that control the add operation; set unused flags to 0:

mediaSampleNotSync

Indicates that the sample to be added is not a sync sample. Set this flag to 1 if the sample is not a sync sample; set it to 0 if the sample is a sync sample.

sampleDecodeTimeOut

A pointer to a time value that represents the sample decode time. After adding the sample data to the media, the function returns in this parameter the time where the sample was inserted. If you don’t want to receive this information, set this parameter to NIL.

Return Value

An error code. Returns noErr if there is no error. You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result.

Discussion

Your application specifies the sample and the media for the operation. This function updates the media so that it contains the sample data. One call to this function can add several samples to a media. This function replaces AddMediaSample; it adds 64-bit support and support for frame reordering video compression (display offset). This function can return these errors:

noErr

Success.

memFullErr

Could not allocate memory.

paramErr

Invalid parameter.

errMediaDoesNotSupportDisplayOffsets

The media does not support nonzero display offsets.

errDisplayTimeAlreadyInUse

There is already a sample with this display time.

errDisplayTimeTooEarly

A sample’s display time would be earlier than the display time of an existing sample that does not have the mediaSampleEarlierDisplayTimesAllowed flag set.

Version Notes

Introduced in QuickTime 7. This function extends and supersedes AddMediaSample. Whereas AddMediaSample takes a Handle+offset+size, AddMediaSample2 takes a Ptr+size.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

AddMediaSampleFromEncodedFrame

Adds sample data and description from an encoded frame to a media.

OSErr AddMediaSampleFromEncodedFrame (
   Media theMedia,
   ICMEncodedFrameRef encodedFrame,
   TimeValue64 *sampleDecodeTimeOut );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia

encodedFrame

An encoded frame token returned by an ICMCompressionSequence.

sampleDecodeTimeOut

A pointer to a time value. After adding the sample data to the media, the function returns the decode time where the first sample was inserted in the time value referred to by this parameter. If you don’t want to receive this information, set this parameter to NULL.

Return Value

An error code. Returns noErr if there is no error. You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result.

Discussion

This is a convenience API to make it easy to add frames emitted by new ICM compression functions to media. It can return these errors:

noErr

Success.

memFullErr

Could not allocate memory.

paramErr

Invalid parameter.

errMediaDoesNotSupportDisplayOffsets

The media does not support nonzero display offsets.

errDisplayTimeAlreadyInUse

There is already a sample with this display time.

errDisplayTimeTooEarly

A sample’s display time would be earlier than the display time of an existing sample that does not have the mediaSampleEarlierDisplayTimesAllowed flag set.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

AddSampleTableToMedia

Adds a sample table to a media.

OSErr AddSampleTableToMedia (
   Media               theMedia,
   QTSampleTableRef    sampleTable,
   SInt64              startSampleNum,
   SInt64              numberOfSamples,
   TimeValue64         *sampleDecodeTimeOut );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

sampleTable

A reference to an opaque sample table object containing sample references to be added to the media.

startSampleNum

The sample number of the first sample reference in the sample table to be added to the media. The first sample’s number is 1.

numberOfSamples

The number of sample references from the sample table to be added to the media.

sampleDecodeTimeOut

A pointer to a time value. After adding the sample references to the media, the function returns the decode time where the first sample was inserted in the time value referred to by this parameter. If you don’t want to receive this information, set this parameter to NULL.

Return Value

An error code. Returns noErr if there is no error. You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result.

Discussion

This function can return these errors:

noErr

Success.

memFullErr

Could not allocate memory.

paramErr

Invalid parameter.

errMediaDoesNotSupportDisplayOffsets

The media does not support nonzero display offsets.

errDisplayTimeAlreadyInUse

There is already a sample with this display time.

errDisplayTimeTooEarly

A sample’s display time would be earlier than the display time of an existing sample that does not have the mediaSampleEarlierDisplayTimesAllowed flag set.

If errDisplayTimeAlreadyInUse or errDisplayTimeTooEarly is returned, no samples are added.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

CopyMediaMutableSampleTable

Obtains information about sample references in a media in the form of a sample table.

OSErr CopyMediaMutableSampleTable (
   Media                      theMedia,
   TimeValue64                startDecodeTime,
   TimeValue64                *sampleStartDecodeTime,
   SInt64                     maxNumberOfSamples,
   TimeValue64                maxDecodeDuration,
   QTMutableSampleTableRef    *sampleTableOut );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

startDecodeTime

A 64-bit time value that represents the starting decode time of the sample references to be retrieved. You must specify this value in the media’s time scale.

sampleStartDecodeTime

A pointer to a time value. The function updates this time value to indicate the actual decode time of the first returned sample reference. If you are not interested in this information, set this parameter to NULL. The returned time may differ from the time you specified with the startDecodeTime parameter. This will occur if the time you specified falls in the middle of a sample.

maxNumberOfSamples

A 64-bit signed integer that contains the maximum number of sample references to be returned. If you set this parameter to 0, the Movie Toolbox uses a value that is appropriate to the media.

maxDecodeDuration

A 64-bit time value that represents the maximum decode duration to be returned. The function does not return samples with greater decode duration than you specify with this parameter. If you set this parameter to 0, the Movie Toolbox uses a value that is appropriate for the media.

sampleTableOut

A reference to an opaque sample table object. When you are done with the returned sample table, release it with QTSampleTableRelease.

Return Value

An error code. Returns memFullErr if it could not allocate memory, paramErr if there was an invalid parameter, or noErr if there is no error. You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result.

Discussion

To find out how many samples were returned in the sample table, call QTSampleTableGetNumberOfSamples.

Version Notes

Introduced in QuickTime 7. This function supersedes GetMediaSampleReferences and GetMediaSampleReferences64.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

DisposeMovieExportStageReachedCallbackUPP

Disposes of a MovieExportStageReachedCallbackUPP pointer.

void DisposeMovieExportStageReachedCallbackUPP (
   MovieExportStageReachedCallbackUPP    userUPP );

Parameters

userUPP

A MovieExportStageReachedCallbackUPP pointer.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: QuickTimeComponents.h

Declared In

DisposeQTTrackPropertyListenerUPP

Disposes a track property listener UPP.

void DisposeQTTrackPropertyListenerUPP (
   QTTrackPropertyListenerUPP userUPP );

Parameters

userUPP

A QTTrackPropertyListenerUPP pointer. See Universal Procedure Pointers in the QuickTime API Reference for more information.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

ExtendMediaDecodeDurationToDisplayEndTime

Prepares a media for the addition of a completely new sequence of samples by ensuring that the media display end time is not later than the media decode end time.

OSErr ExtendMediaDecodeDurationToDisplayEndTime (
   Media      theMedia,
   Boolean    *mediaChanged );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

mediaChanged

A pointer to a Boolean that returns TRUE if any samples in the media were adjusted, FALSE otherwise. If you don’t want to receive this information, set this parameter to NULL.

Return Value

An error code. Returns memFullErr if it could not allocate memory, paramErr if there was an invalid parameter, or noErr if there is no error. You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result.

Discussion

After adding a complete, well-formed set of samples to a media, the media’s display end time should be the same as the media’s decode end time (also called the media decode duration). However, this is not necessarily the case after individual sample-adding operations, and hence it is possible for a media to be left with a display end time later than its decode end time (if adding a sequence of frames is aborted halfway, for example).

This may make it difficult to add a new group of samples, because a well-formed group of samples’ earliest display time should be the same as the first frame’s decode time. If such a well-formed group is added to an incompletely finished media, frames from the old and new groups frames might collide in display time.

This function prevents any such collision or overlap by extending the last sample’s decode duration as necessary. It ensures that the next added sample will have a decode time no earlier than the media’s display end time. If this was already the case, it makes no change to the media.

You can call this function before you begin adding samples to a media if you’re not certain that the media was left in a well-finished state. You do not need to call it before adding samples to a newly created media, nor should you call it between sample additions from the same compression session.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetDSequenceNonScheduledDisplayDirection

Returns the display direction for a decompress sequence.

OSErr GetDSequenceNonScheduledDisplayDirection (
   ImageSequence    sequence,
   Fixed            *rate );

Parameters

sequence

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

rate

A pointer to the display direction. Negative values represent backward display and positive values represent forward display.

Return Value

An error code. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: ImageCompression.h

Declared In

GetDSequenceNonScheduledDisplayTime

Gets the display time for a decompression sequence.

OSErr GetDSequenceNonScheduledDisplayTime (
   ImageSequence    sequence,
   TimeValue64      *displayTime,
   TimeScale        *displayTimeScale );

Parameters

sequence

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

displayTime

A pointer to a variable to hold the display time.

displayTimeScale

A pointer to a variable to hold the display time scale.

Return Value

An error code. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: ImageCompression.h

Declared In

GetMediaAdvanceDecodeTime

Returns the advance decode time of a media.

TimeValue64 GetMediaAdvanceDecodeTime (
   Media    theMedia );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

Return Value

A 64-bit time value that represents the media’s advance decode time. A media’s advance decode time is the absolute value of the greatest-magnitude negative display offset of its samples, or 0 if there are no samples with negative display offsets. This is the amount that the decode time axis must be adjusted ahead of the display time axis to ensure that no sample’s adjusted decode time is later than its display time. For media without nonzero display offsets, the advance decode time is 0.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMediaDataSizeTime64

Determines the size, in bytes, of the sample data in a media segment.

OSErr GetMediaDataSizeTime64 (
   Media          theMedia,
   TimeValue64    startDisplayTime,
   TimeValue64    displayDuration,
   SInt64         *dataSize );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

startDisplayTime

A 64-bit time value that specifies the starting point of the segment in media display time.

displayDuration

A 64-bit time value that specifies the duration of the segment in media display time.

dataSize

A pointer to a variable to receive the size, in bytes, of the sample data in the defined media segment.

Return Value

An error code. Returns noErr if there is no error. You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result.

Discussion

The only difference between this function and GetMediaDataSize64 is that this function uses 64-bit time values and returns a 64-bit size.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMediaDecodeDuration

Returns the decode duration of a media.

TimeValue64 GetMediaDecodeDuration (
   Media    theMedia );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

Return Value

A 64-bit time value that repre sents the media’s decode duration. A media’s decode duration is the sum of the decode durations of its samples.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMediaDisplayDuration

Returns the display duration of a media.

TimeValue64 GetMediaDisplayDuration (
   Media    theMedia );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

Return Value

A 64-bit time value that represents the media’s display duration. A media’s display duration is its display end time minus its display start time. For media without nonzero display offsets, the decode duration and display duration are the same.

Discussion

When inserting media with display offsets into a track, use display time:

InsertMediaIntoTrack( track,

                0,                                   // track start time

                GetMediaDisplayStartTime( media ),   // media start time

                GetMediaDisplayDuration( media ),

                fixed1 );

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMediaDisplayEndTime

Returns the display end time of a media.

TimeValue64 GetMediaDisplayEndTime (
   Media    theMedia );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

Return Value

A 64-bit time value that represents the media’s display end time. A media’s display end time is the sum of the display time and decode duration of the sample with the greatest display time. For media without nonzero display offsets, the display end time is the same as the media’s decode duration.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMediaDisplayStartTime

Returns the display start time of a media.

TimeValue64 GetMediaDisplayStartTime (
   Media    theMedia );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

Return Value

A 64-bit time value that represents the media’s display start time. A media’s display start time is the earliest display time of any of its samples. For media without nonzero display offsets, the display start time is always 0.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMediaNextInterestingDecodeTime

Searches for decode times of interest in a media.

void GetMediaNextInterestingDecodeTime (
   Media          theMedia,
   short          interestingTimeFlags,
   TimeValue64    decodeTime,
   Fixed          rate,
   TimeValue64    *interestingDecodeTime,
   TimeValue64    *interestingDecodeDuration );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

interestingTimeFlags

Flags that determine the search criteria. Note that you may set only one of the nextTimeMediaSample, nextTimeMediaEdit, or nextTimeSyncSample flags to 1. Set unused flags to 0:

nextTimeMediaSample

Set this flag to 1 to search for the next sample.

nextTimeMediaEdit

Set this flag to 1 to search for the next group of samples.

nextTimeSyncSample

Set this flag to 1 to search for the next sync sample.

nextTimeEdgeOK

Set this flag to 1 to accept information about elements that begin or end at the time specified by the decodeTime parameter. When this flag is set the function returns valid information about the beginning and end of a media.

decodeTime

Specifies the starting point for the search in decode time. This time value must be expressed in the media’s time scale.

rate

The search direction. Negative values cause the Movie Toolbox to search backward from the starting point specified in the time parameter. Other values cause a forward search.

interestingDecodeTime

On return, a pointer to a 64-bit time value in decode time. The Movie Toolbox returns the first time value it finds that meets the search criteria specified in the flags parameter. This time value is in the media’s time scale. If there are no times that meet the search criteria you specify, the Movie Toolbox sets this value to –1. Set this parameter to NULL if you are not interested in this information.

interestingDecodeDuration

On return, a pointer to a 64-bit time value in decode time. The Movie Toolbox returns the duration of the interesting time in the media’s time coordinate system. Set this parameter to NULL if you don’t want this information; this lets the function works faster.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMediaNextInterestingDisplayTime

Searches for display times of interest in a media.

void GetMediaNextInterestingDisplayTime (
   Media          theMedia,
   short          interestingTimeFlags,
   TimeValue64    displayTime,
   Fixed          rate,
   TimeValue64    *interestingDisplayTime,
   TimeValue64    *interestingDisplayDuration );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

interestingTimeFlags

Flags that determine the search criteria. Note that you may set only one of the nextTimeMediaSample, nextTimeMediaEdit, or nextTimeSyncSample flags to 1. Set unused flags to 0:

nextTimeMediaSample

Set this flag to 1 to search for the next sample.

nextTimeMediaEdit

Set this flag to 1 to search for the next group of samples.

nextTimeSyncSample

Set this flag to 1 to search for the next sync sample.

nextTimeEdgeOK

Set this flag to 1 to accept information about elements that begin or end at the time specified by the decodeTime parameter. When this flag is set the function returns valid information about the beginning and end of a media.

displayTime

Specifies the starting point for the search in display time. This time value must be expressed in the media’s time scale.

rate

The search direction. Negative values cause the Movie Toolbox to search backward from the starting point specified in the time parameter. Other values cause a forward search.

interestingDisplayTime

On return, a pointer to a 64-bit time value in display time. The Movie Toolbox returns the first time value it finds that meets the search criteria specified in the flags parameter. This time value is in the media’s time scale. If there are no times that meet the search criteria you specify, the Movie Toolbox sets this value to –1. Set this parameter to NIL if you are not interested in this information.

interestingDisplayDuration

On return, a pointer to a 64-bit time value in display time. The Movie Toolbox returns the duration of the interesting time in the media’s time coordinate system. Set this parameter to NIL if you don’t want this information; this lets the function works faster.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMediaSample2

Retrieves sample data from a media file.

OSErr GetMediaSample2 (
   Media                      theMedia,
   UInt8                      *dataOut,
   ByteCount                  maxDataSize,
   ByteCount                  *size,
   TimeValue64                decodeTime,
   TimeValue64                *sampleDecodeTime,
   TimeValue64                *decodeDurationPerSample,
   TimeValue64                *displayOffset,
   SampleDescriptionHandle    sampleDescriptionH,
   ItemCount                  *sampleDescriptionIndex,
   ItemCount                  maxNumberOfSamples,
   ItemCount                  *numberOfSamples,
   MediaSampleFlags           *sampleFlags );

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

dataOut

A pointer to a buffer to receive sample data. The buffer must be large enough to contain at least maxDataSize bytes. If you do not want to receive sample data, pass NULL.

maxDataSize

The maximum number of bytes allocated to hold the sample data.

size

A pointer to memory where the function returns the number of bytes of sample data returned in the memory area specified by dataOut. Set this parameter to NULL if you are not interested in this information.

decodeTime

The starting time of the sample to be retrieved in decode time. You must specify this value in the media’s time scale.

sampleDecodeTime

A pointer to a time value in decode time. The function updates this time value to indicate the actual time of the returned sample data. (The returned time may differ from the time you specified with the time parameter. This will occur if the time you specified falls in the middle of a sample.) If you are not interested in this information, set this parameter to NULL.

decodeDurationPerSample

A pointer to a time value in decode time. The Movie Toolbox returns the duration of each sample in the media. Set this parameter to NULL if you don’t want this information.

displayOffset

A pointer to a time value. The function updates this time value to indicate the display offset of the returned sample. This time value is expressed in the media’s time scale. Set this parameter to NULL if you don’t want this information.

sampleDescriptionH

A handle to a SampleDescription structure. The function returns the sample description corresponding to the returned sample data. The function resizes this handle as appropriate. If you don’t want a SampleDescription structure, set this parameter to NIL.

sampleDescriptionIndex

A pointer to a long integer. The function returns an index value to the SampleDescription structure that corresponds to the returned sample data. You can retrieve the structure by calling GetMediaSampleDescription and passing this index in the descH parameter. If you don’t want this information, set this parameter to NIL.

maxNumberOfSamples

The maximum number of samples to be returned. The Movie Toolbox does not return more samples than you specify with this parameter. If you set this parameter to 0, the Movie Toolbox uses a value that is appropriate for the media, and returns that value in the field referenced by the numberOfSamples parameter.

numberOfSamples

A pointer to a long integer. The function updates the field referred to by this parameter with the number of samples it actually returns. If you don’t want this information, set this parameter to NULL.

sampleFlags

A pointer to a short integer in which the function returns flags that describe the sample. Unused flags are set to 0. If you don’t want this information, set this parameter to NULL:

mediaSampleNotSync

This flag is set to 1 if the sample is not a sync sample and to 0 if the sample is a sync sample.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError. It returns paramErr if there is a bad parameter value, maxSizeToGrowTooSmall if the sample data is larger than maxDataSize, or noErr if there is no error.

Discussion

Whereas GetMediaSample takes a resizable Handle and a maxSizeToGrow parameter, GetMediaSample2 takes a pointer and a maxDataSize parameter. If you want to read a sample into a Handle, you can use the following code:

 OSErr GetMediaSampleUsingHandle (Media theMedia, Handle dataHOut,

                 ByteCount maxSizeToGrow, ByteCount *size,

                 TimeValue64 decodeTime, TimeValue64 *sampleDecodeTime,

                 TimeValue64 *decodeDurationPerSample,

                 TimeValue64 *displayOffset,

                 SampleDescriptionHandle sampleDescriptionH,

                 ItemCount *sampleDescriptionIndex,

                 ItemCount maxNumberOfSamples,

                 ItemCount *numberOfSamples,

                 MediaSampleFlags *sampleFlags)

  {

      OSErr err = noErr;

      ByteCount actualSize = 0;

      err = GetMediaSample2(theMedia,

                            *dataHOut,

                            GetHandleSize(dataHOut),

                            &actualSize,

                            decodeTime,

                            sampleDecodeTime,

                            decodeDurationPerSample,

                            displayOffset,

                            sampleDescriptionH,

                            sampleDescriptionIndex,

                            maxNumberOfSamples,

                            numberOfSamples,

                            sampleFlags);

      if ((maxSizeToGrowTooSmall == err)

      && ((0 == maxSizeToGrow) || (actualSize <= maxSizeToGrow)) {

          SetHandleSize(dataHOut, actualSize);

          err = MemError();

          if (err) goto bail;

          err = GetMediaSample2(theMedia,

                                *dataHOut,

                                GetHandleSize(dataHOut),

                                &actualSize,

                                decodeTime,

                                sampleDecodeTime,

                                decodeDurationPerSample,

                                displayOffset,

                                sampleDescriptionH,

                                sampleDescriptionIndex,

                                maxNumberOfSamples,

                                numberOfSamples,

                                sampleFlags);

      }

      if( size )

          *size = actualSize;

  bail:

      return err;

  }

Version Notes

Introduced in QuickTime 7. This function extends and supersedes GetMediaSample. It will only return multiple samples that all have the same decode duration per sample, the same display offset, the same sample description, and the same size per sample.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieAudioBalance

Returns the balance value for the audio mix of a movie currently playing.

OSStatus GetMovieAudioBalance (
   Movie      m,
   Float32    *leftRight,
   UInt32     flags );

Parameters

m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

leftRight

On return, a pointer to the current balance setting for the movie. The balance setting is a 32-bit floating-point value that controls the relative volume of the left and right sound channels. A value of 0 sets the balance to neutral. Positive values up to 1.0 shift the balance to the right channel, negative values up to –1.0 to the left channel.

flags

Not used; set to 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The movie’s balance setting is not stored in the movie; it is used only until the movie is closed. See SetMovieAudioBalance.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieAudioContext

Returns the current audio context for a movie.

OSStatus GetMovieAudioContext (
   Movie                movie,
   QTAudioContextRef    *audioContext);

Parameters

movie

The movie.

audioContext

A pointer to a variable to receive the audio context.

Return Value

An error code. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieAudioFrequencyLevels

Returns the current frequency meter levels of a movie mix.

OSStatus GetMovieAudioFrequencyLevels (
   Movie                     m,
   FourCharCode              whatMixToMeter,
   QTAudioFrequencyLevels    *pAveragePowerLevels );

Parameters

m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

whatMixToMeter

The applicable mix of audio channels in the movie; see “Movie Audio Mixes”.

pAveragePowerLevels

A pointer to a QTAudioFrequencyLevels structure (page 339).

Return Value

An error code. Returns noErr if there is no error.

Discussion

In the structure pointed to by pAveragePowerLevels, the numChannels field must be set to the number of channels in the movie mix being metered and the numBands field must be set to the number of bands being metered (as previously configured). Enough memory for the structure must be allocated to hold 32-bit values for all bands in all channels. This function returns the current frequency meter levels in the level field of the structure, with all the band levels for the first channel first, all the band levels for the second channel next and so on.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieAudioFrequencyMeteringBandFrequencies

Returns the chosen middle frequency for each band in the configured frequency metering of a particular movie mix.

OSStatus GetMovieAudioFrequencyMeteringBandFrequencies (
   Movie           m,
   FourCharCode    whatMixToMeter,
   UInt32          numBands,
   Float32         *outBandFrequencies );

Parameters

m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

whatMixToMeter

The applicable mix of audio channels in the movie; see “Movie Audio Mixes”.

numBands

The number of bands to examine.

outBandFrequencies

A pointer to an array of frequencies, each expressed in Hz.

Return Value

An error code. Returns noErr if there is no error.

Discussion

You can use this function to label a visual meter in a user interface.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieAudioFrequencyMeteringNumBands

Returns the number of frequency bands being metered for a movie’s specified audio mix.

OSStatus GetMovieAudioFrequencyMeteringNumBands (
   Movie           m,
   FourCharCode    whatMixToMeter,
   UInt32          *outNumBands );

Parameters

m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

whatMixToMeter

The applicable mix of audio channels in the movie; see “Movie Audio Mixes”.

outNumBands

A pointer to memory that stores the number of frequency bands currently being metered for the movie’s specified audio mix.

Return Value

An error code. Returns noErr if there is no error.

Discussion

See SetMovieAudioFrequencyMeteringNumBands.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieAudioGain

Returns the gain value for the audio mix of a movie currently playing.

OSStatus GetMovieAudioGain (
   Movie      m,
   Float32    *gain,
   UInt32     flags );

Parameters

m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

gain

A 32-bit floating-point gain value of 0 or greater. 0.0 is silent, 0.5 is –6 dB, 1.0 is 0 dB (the audio from the movie is not modified), 2.0 is +6 dB, etc. The gain level can be set higher than 1.0 to allow quiet movies to be boosted in volume. Gain settings higher than 1.0 may result in audio clipping.

flags

Not used; set to 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The movie gain setting is not stored in the movie; it is used only until the movie is closed. See SetMovieAudioGain.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieAudioMute

Returns the mute value for the audio mix of a movie currently playing.

OSStatus GetMovieAudioMute (
   Movie      m,
   Boolean    *muted,
   UInt32     flags );

Parameters

m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

muted

Returns TRUE if the movie audio is currently muted, FALSE otherwise.

flags

Not used; set to 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The movie mute setting is not stored in the movie; it is used only until the movie is closed. See SetMovieAudioMute.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieAudioVolumeLevels

Returns the current volume meter levels of a movie.

OSStatus GetMovieAudioVolumeLevels (
   Movie                  m,
   FourCharCode           whatMixToMeter,
   QTAudioVolumeLevels    *pAveragePowerLevels,
   QTAudioVolumeLevels    *pPeakHoldLevels );

Parameters

m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

whatMixToMeter

The applicable mix of audio channels in the movie; see “Movie Audio Mixes”.

pAveragePowerLevels

A pointer to a QTAudioVolumeLevels structure that stores the average power level of each channel in the mix, measured in decibels. 0.0 dB for each channel means full volume, –6.0 dB means half volume, –12.0 dB means quarter volume, and –infinite dB means silence. Pass NULL for this parameter if you are not interested in average power levels.

pPeakHoldLevels

A pointer to a QTAudioVolumeLevels structure that stores the peak hold level of each channel in the mix, measured in decibels. 0.0 dB for each channel means full volume, –6.0 dB means half volume, –12.0 dB means quarter volume, and –infinite dB means silence. Pass NULL for this parameter if you are not interested in peak hold levels.

Return Value

An error code. Returns noErr if there is no error.

Discussion

If either pAveragePowerLevels or pPeakHoldLevels returns non-NULL, it must have the numChannels field in its QTAudioVolumeLevels structure set to the number of channels in the movie mix being metered and the memory allocated for the structure must be large enough to hold levels for all those channels.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieAudioVolumeMeteringEnabled

Returns the enabled or disabled status of volume metering of a particular audio mix of a movie.

OSStatus GetMovieAudioVolumeMeteringEnabled (
   Movie           m,
   FourCharCode    whatMixToMeter,
   Boolean         *enabled );

Parameters

m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

whatMixToMeter

The applicable mix of audio channels in the movie; see “Movie Audio Mixes”.

enabled

Returns TRUE if audio volume metering is enabled, FALSE if it is disabled.

Return Value

An error code. Returns noErr if there is no error.

Discussion

See SetMovieAudioVolumeMeteringEnabled.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieVisualBrightness

Returns the brightness adjustment for the movie.

OSStatus GetMovieVisualBrightness (
   Movie movie,
   Float32 *brightnessOut,
   UInt32 flags );

Parameters

movie

The movie.

brightnessOut

Current brightness adjustment.

flags

Reserved. Pass 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The brightness adjustment for the movie. The value is a Float32 for which -1.0 means full black, 0.0 means no adjustment, and 1.0 means full white. The setting is not stored in the movie. It is only used until the movie is closed, at which time it is not saved.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieVisualContext

Returns the current visual context for a movie.

OSStatus GetMovieVisualContext (
   Movie      movie,
   QTVisualContextRef    *visualContext;

Parameters

movie

The movie.

visualContext

A pointer to a variable to receive the visual context.

Return Value

An error code. Returns noErr if there is no error. Returns memFullErr if memory cannot be allocated. Returns kQTVisualContextRequiredErr if the movie is not using a visual context. Returns paramErr if the movie or visualContextOut is NULL.

Discussion

Returns the QTVisualContext object associated with the movie. You are responsible for retaining and releasing the object as needed (that is, if the returned object has not been retained for you). If the visual context was set to NULL (see SetMovieVisualContext), noErr is returned and visualContextOut receives NULL.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieVisualContrast

Returns the contrast adjustment for the movie.

OSStatus GetMovieVisualContrast (
   Movie           movie,
   Float32         *contrastOut,
   UInt32          flags );

Parameters

movie

The movie.

contrastOut

Current contrast adjustment.

flags

Reserved. Pass 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The contrast adjustment for the movie. The value is a Float32 percentage (1.0f = 100%), such that 0.0 gives solid grey.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieVisualHue

Returns the hue adjustment for the movie.

OSStatus GetMovieVisualHue (
   Movie movie,
   Float32 *hueOut,
   UInt32 flags );

Parameters

movie

The movie.

hueOut

Current hue adjustment. (Float32)

flags

Reserved. Pass 0. (UInt32)

Return Value

An error code. Returns noErr if there is no error.

Discussion

The hue adjustment for the movie. The value is a Float32 between -1.0 and 1.0, with 0.0 meaning no adjustment. This adjustment wraps around, such that -1.0 and 1.0 yield the same result. The setting is not stored in the movie. It is only used until the movie is closed, at which time it is not saved.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetMovieVisualSaturation

Returns the color saturation adjustment for the movie.

OSStatus GetMovieVisualSaturation (
   Movie movie,
   Float32 *saturationOut,
   UInt32 flags );

Parameters

movie

The movie.

saturationOut

Current saturation adjustment.(Float32)

flags

Reserved. Pass 0. (UInt32)

Return Value

An error code. Returns noErr if there is no error.

Discussion

The color saturation adjustment for the movie. The value is a Float32 percentage (1.0f = 100%), such that 0.0 gives grayscale. The setting is not stored in the movie. It is only used until the movie is closed, at which time it is not saved.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetTrackAudioGain

Returns the gain value for the audio mix of a track currently playing.

OSStatus GetTrackAudioGain (
   Track      t,
   Float32    *gain,
   UInt32     flags );

Parameters

t

A track identifier, which your application obtains from such functions as NewMovieTrack and GetMovieTrack.

gain

A 32-bit floating-point gain value of 0 or greater. 0.0 is silent, 0.5 is –6 dB, 1.0 is 0 dB (the audio from the track is not modified), 2.0 is +6 dB, etc. The gain level can be set higher than 1.0 to allow quiet tracks to be boosted in volume. Gain settings higher than 1.0 may result in audio clipping.

flags

Not used; set to 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The track gain setting is not stored in the movie; it is used only until the movie is closed. See SetTrackAudioGain.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetTrackAudioMute

Returns the mute value for the audio mix of a track currently playing.

OSStatus GetTrackAudioMute (
   Track      t,
   Boolean    *muted,
   UInt32     flags );

Parameters

t

A track identifier, which your application obtains from such functions as NewMovieTrack and GetMovieTrack.

muted

Returns TRUE if the track’s audio is currently muted, FALSE otherwise.

flags

Not used; set to 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The track’s mute setting is not stored in the movie; it is used only until the movie is closed. See SetTrackAudioMute.

Version Notes

Introduced in QuickTime 7.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

GetTrackEditRate64

Returns the rate of the track edit of a specified track at an indicated time.

Fixed GetTrackEditRate64 (
   Track          theTrack,
   TimeValue64    atTime );

Parameters

theTrack

A track identifier, which your application obtains from such functions as NewMovieTrack and GetMovieTrack.

atTime

A 64-bit time value that indicates the time at which the rate of a track edit (of a track identified in the parameter theTrack) is to be determined.

Return Value

The rate of the track edit of the specified track at the specified time.

Discussion

This function is useful if you are stepping through track edits directly in your application or if you are a client of QuickTime’s base media handler.

Version Notes

Introduced in QuickTime 7. This function is a 64-bit replacement for GetTrackEditRate.

Availability

• Carbon status: Supported C interface file: Movies.h

Declared In

HIMovieViewChangeAttributes

Changes the views attributes.

OSStatus HIMovieViewChangeAttributes (
   HIViewRef inView,
   OptionBits inAttributesToSet,
   OptionBits inAttributesToClear );

Parameters

inView

The HIMovieView.

inAttributesToSet

Attributes to set.

inAttributesToClear

Attributes to clear.

Return Value

An error code. Returns noErr if there is no error.

Discussion

Setting an attribute takes precedence over clearing the attribute.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: HIMovieView.h

Declared In

HIMovieViewCreate

Creates an HIMovieView object.

OSStatus HIMovieViewCreate (
   Movie inMovie,
   OptionBits inAttributes,
   HIViewRef *outMovieView );

Parameters

inMovie

Initial movie to view; may be NULL.

inAttributes

Initial HIMovieView attributes.

outMovieView

Points to variable to receive new HIMovieView.

Return Value

Undocumented.

Discussion

If successful, the created view will have a single retain count.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: HIMovieView.h

Declared In

HIMovieViewGetAttributes

Returns the view’s current attributes.

OptionBits HIMovieViewGetAttributes (
   HIViewRef inView );

Parameters

inView

The HIMovieView.

Return Value

Undocumented.

Discussion

The view’s current attributes are returned.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: HIMovieView.h

Declared In

HIMovieViewGetControllerBarSize

Returns the size of the visible movie controller bar.

HISize HIMovieViewGetControllerBarSize (
   HIViewRef inView );

Parameters

inView

The HIMovieView.

Return Value

Undocumented.

Discussion

The size of the visible movie controller bar is returned.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: HIMovieView.h

Declared In

HIMovieViewGetMovie

Returns the view’s current movie.

Movie HIMovieViewGetMovie (
   HIViewRef inView );

Parameters

inView

The HIMovieView.

Return Value

Undocumented.

Discussion

The view’s current movie is returned.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: HIMovieView.h

Declared In

HIMovieViewGetMovieController

Returns the view’s current movie controller.

MovieController HIMovieViewGetMovieController (
   HIViewRef inView );

Parameters

inView

The HIMovieView.

Return Value

Undocumented.

Discussion

The view’s current movie controller is returned.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: HIMovieView.h

Declared In

HIMovieViewPause

Pauses the view’s current movie.

OSStatus HIMovieViewPause (
   HIViewRef movieView );

Parameters

movieView

The movie view.

Return Value

An error code. Returns noErr if there is no error.

Discussion

This is a convenience routine to pause the view’s current movie. If the movie is already paused, this function does nothing.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: HIMovieView.h

Declared In

HIMovieViewPlay

Plays the view’s current movie.

OSStatus HIMovieViewPlay (
   HIViewRef movieView );

Parameters

movieView

The movie view.

Return Value

An error code. Returns noErr if there is no error.

Discussion

This is a convenience routine to play the view’s current movie. If the movie is already playing, this function does nothing.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: HIMovieView.h

Declared In

HIMovieViewSetMovie

Sets the view’s current movie.

OSStatus HIMovieViewSetMovie (
   HIViewRef inView,
   Movie inMovie );

Parameters

inView

The HIMovieView.

inMovie

The new movie to display.

Return Value

An error code. Returns noErr if there is no error.

Discussion

This routine sets the view’s current movie.

Version Notes

Introduced in QuickTime 7

Availability

• Carbon status: Supported C interface file: HIMovieView.h

Declared In

ICMCompressionFrameOptionsCreate

Creates a frame compression options object.

OSStatu