Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
New Functions, Data Types, and Constants in QuickTime 7 for Windows
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
andGetTrackMedia
.- 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 anImageDescription
structure. A media that contains sound requires that you supply aSoundDescription
structure. If the media does not require aSampleDescription
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
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
andGetTrackMedia
- 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
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
andGetTrackMedia
.- 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
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
andGetTrackMedia
.- 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
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
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
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
andGetTrackMedia
.- mediaChanged
A pointer to a
Boolean
that returnsTRUE
if any samples in the media were adjusted,FALSE
otherwise. If you don’t want to receive this information, set this parameter toNULL
.
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
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
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
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
andGetTrackMedia
.
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
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
andGetTrackMedia
.- 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
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
andGetTrackMedia
.
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
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
andGetTrackMedia
.
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
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
andGetTrackMedia
.
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
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
andGetTrackMedia
.
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
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
andGetTrackMedia
.- interestingTimeFlags
Flags that determine the search criteria. Note that you may set only one of the
nextTimeMediaSample
,nextTimeMediaEdit
, ornextTimeSyncSample
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
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
andGetTrackMedia
.- interestingTimeFlags
Flags that determine the search criteria. Note that you may set only one of the
nextTimeMediaSample
,nextTimeMediaEdit
, ornextTimeSyncSample
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
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
andGetTrackMedia
.- 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 aSampleDescription
structure, set this parameter toNIL
.- 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 callingGetMediaSampleDescription
and passing this index in the descH parameter. If you don’t want this information, set this parameter toNIL
.- 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
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
, andNewMovieFromHandle
.- 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
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
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
, andNewMovieFromHandle
.- whatMixToMeter
The applicable mix of audio channels in the movie; see
“Movie Audio Mixes”
.- pAveragePowerLevels
A pointer to a
QTAudioFrequencyLevels
structure(page 310)
.
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
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
, andNewMovieFromHandle
.- 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
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
, andNewMovieFromHandle
.- 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
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
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
, andNewMovieFromHandle
.- 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
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
, andNewMovieFromHandle
.- 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
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
, andNewMovieFromHandle
.- 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. PassNULL
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. PassNULL
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
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
, andNewMovieFromHandle
.- 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
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
GetQTApplicationDirectory
Returns the path of the QuickTime Applications directory.
UINT GetQTApplicationDirectory ( LPSTR lpBuffer, UINT uSize );
Parameters
- lpBuffer
A pointer to the buffer to receive the null-terminated string containing the path to the QuickTime Applications directory. This path does not end with a backslash unless the system directory is the root directory.
- uSize
The maximum size of the buffer, in TCHARs. This value should be set to at least MAX_PATH+1 to allow sufficient space for the path and the null terminator.
Return Value
If the function succeeds,
the return value is the length, in TCHARs, of the string copied
to the buffer, not including the terminating null character. If the
length is greater than the size of the buffer, the return value
is the size of the buffer required to hold the path. If the function
fails, the return value is zero. To get extended error information,
call GetLastError
.
Discussion
The QuickTime Applications directory contains the QuickTime
applications files, such as QuickTime Player and others. Note that
this call looks up the value of HKEY_LOCAL_MACHINE\SOFTWARE\Apple
Computer, Inc.\QuickTime\InstallDir
, which
is the root QuickTime folder that the user chose to install into.
Version Notes
Introduced in QuickTime 7 for Windows.
Availability
- C interface file:
QTLoadLibraryUtils.h
GetQTComponentDirectory
Returns the path of the QuickTime Components directory.
UINT GetQTComponentDirectory ( LPSTR lpBuffer, UINT uSize );
Parameters
- lpBuffer
A pointer to the buffer to receive the null-terminated string containing the path to the QuickTime Components directory. This path does not end with a backslash unless the system directory is the root directory.
- uSize
The maximum size of the buffer, in TCHARs. This value should be set to at least MAX_PATH+1 to allow sufficient space for the path and the null terminator.
Return Value
If the function succeeds,
the return value is the length, in TCHARs, of the string copied
to the buffer, not including the terminating null character. If the
length is greater than the size of the buffer, the return value
is the size of the buffer required to hold the path. If the function
fails, the return value is zero. To get extended error information,
call GetLastError
.
Discussion
The QuickTime Components directory contains any third-party
or user-installed component files. Note that this call looks up
the value of HKEY_LOCAL_MACHINE\SOFTWARE\Apple
Computer, Inc.\QuickTime\QTComponentsDir
,
which is where you should put your components
Version Notes
Introduced in QuickTime 7 for Windows.
Availability
- C interface file:
QTLoadLibraryUtils.h
GetQTExtensionDirectory
Returns the path of the QuickTime Extensions directory.
UINT GetQTExtensionDirectory ( LPSTR lpBuffer, UINT uSize );
Parameters
- lpBuffer
A pointer to the buffer to receive the null-terminated string containing the path to the QuickTime Extensions directory. This path does not end with a backslash unless the system directory is the root directory.
- uSize
The maximum size of the buffer, in TCHARs. This value should be set to at least MAX_PATH+1 to allow sufficient space for the path and the null terminator.
Return Value
If the function succeeds,
the return value is the length, in TCHARs, of the string copied
to the buffer, not including the terminating null character. If the
length is greater than the size of the buffer, the return value
is the size of the buffer required to hold the path. If the function
fails, the return value is zero. To get extended error information,
call GetLastError
.
Discussion
The QuickTime Extensions directory contains the QuickTime
extensions files, whose names ends with .qtx
and .qtr
.
(A .qtx
file contains
the data fork of an extension––a Windows DLL, while a .qtr
file
contains the resource fork of an extension for Macintosh-style resources).
Note that this call looks up the value of HKEY_LOCAL_MACHINE\SOFTWARE\Apple
Computer, Inc.\QuickTime\QTExtDir
, which points to
the folder where the extensions are installed.
Version Notes
Introduced in QuickTime 7 for Windows.
Availability
- C interface file:
QTLoadLibraryUtils.h
GetQTSystemDirectory
Returns the path of the QuickTime System directory.
UINT GetQTSystemDirectory ( LPSTR lpBuffer, UINT uSize );
Parameters
- lpBuffer
A pointer to the buffer to receive the null-terminated string containing the path to the QuickTime System directory. This path does not end with a backslash unless the system directory is the root directory.
- uSize
The maximum size of the buffer, in TCHARs. This value should be set to at least MAX_PATH+1 to allow sufficient space for the path and the null terminator.
Return Value
If the function succeeds,
the return value is the length, in TCHARs, of the string copied
to the buffer, not including the terminating null character. If the
length is greater than the size of the buffer, the return value
is the size of the buffer required to hold the path. If the function
fails, the return value is zero. To get extended error information,
call GetLastError
.
Discussion
The QuickTime System directory contains all the necessary
QuickTime system files such as extensions––that is, codecs,
file importers, and so on––dynamic link libraries, resources, and
others. Note that this call looks up the value of HKEY_LOCAL_MACHINE\SOFTWARE\Apple Computer,
Inc.\QuickTime\QTSysDir
, which points to the
folder where the system components are installed.
Version Notes
Introduced in QuickTime 7 for Windows.
Availability
- C interface file:
QTLoadLibraryUtils.h
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
andGetMovieTrack
.- 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
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
andGetMovieTrack
.- 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
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
andGetMovieTrack
.- 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
ICMCompressionFrameOptionsCreate
Creates a frame compression options object.
OSStatus ICMCompressionFrameOptionsCreate ( CFAllocatorRef allocator, ICMCompressionSessionRef session, ICMCompressionFrameOptionsRef *options );
Parameters
- allocator
An allocator. Pass
NULL
to use the default allocator.- session
A compression session reference. This reference is returned by
ICMCompressionSessionCreate
.- options
On return, a reference to a new frame compression options object.
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
ICMCompressionFrameOptionsCreateCopy
Copies a frame compression options object.
OSStatus ICMCompressionFrameOptionsCreateCopy ( CFAllocatorRef allocator, ICMCompressionFrameOptionsRef originalOptions, ICMCompressionFrameOptionsRef *copiedOptions );
Parameters
- allocator
An allocator. Pass
NULL
to use the default allocator.- originalOptions
A frame compression options reference. This reference is returned by
ICMCompressionFrameOptionsCreate
.- copiedOptions
On return, a reference to a copy of the frame compression options object passed in originalOptions.
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
ICMCompressionFrameOptionsGetForceKeyFrame
Retrieves the force key frame flag.
Boolean ICMCompressionFrameOptionsGetForceKeyFrame ( ICMCompressionFrameOptionsRef options );
Parameters
- options
A compression frame options reference. This reference is returned by
ICMCompressionFrameOptionsCreate
.
Return Value
Returns TRUE
if
frames are forced to be compressed as key frames, FALSE
otherwise.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionFrameOptionsGetFrameType
Retrieves the frame
type
setting.
ICMFrameType ICMCompressionFrameOptionsGetFrameType ( ICMCompressionFrameOptionsRef options );
Parameters
- options
A compression frame options reference. This reference is returned by
ICMCompressionFrameOptionsCreate
.
Return Value
On return, one of
the frame
types listed below.
Discussion
This function can return one of these constants:
kICMFrameType_I = 'I'
An I frame.
kICMFrameType_P = 'P'
A P frame.
kICMFrameType_B = 'B'
A B frame.
kICMFrameType_Unknown = 0
A frame of unknown type.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionFrameOptionsGetProperty
Retrieves the value of a specific property of a compression frame options object.
OSStatus ICMCompressionFrameOptionsGetProperty ( ICMCompressionFrameOptionsRef options, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ComponentValuePtr outPropValueAddress, ByteCount *outPropValueSizeUsed );
Parameters
- options
A compression frame options reference. This reference is returned by
ICMCompressionFrameOptionsCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueAddress
A pointer to a variable to receive the returned property’s value.
- outPropValueSizeUsed
On return, a pointer to the number of bytes actually used to store the property.
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
ICMCompressionFrameOptionsGetPropertyInfo
Retrieves information about properties of a compression frame options object.
OSStatus ICMCompressionFrameOptionsGetPropertyInfo ( ICMCompressionFrameOptionsRef options, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ComponentValueType *outPropType, ByteCount *outPropValueSize, UInt32 *outPropertyFlags );
Parameters
- options
A compression frame options reference. This reference is returned by
ICMCompressionFrameOptionsCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueSize
A pointer to the size of the returned property’s value.
- outPropFlags
On return, a pointer to flags representing the requested information about the property.
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
ICMCompressionFrameOptionsGetTypeID
Returns the type ID for the current frame compression options object.
CFTypeID ICMCompressionFrameOptionsGetTypeID ( void );
Return Value
A CFTypeID
value.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionFrameOptionsRelease
Decrements the retain count of a frame compression options object.
void ICMCompressionFrameOptionsRelease ( ICMCompressionFrameOptionsRef options );
Parameters
- options
A reference to a frame compression options object.This reference is returned by
ICMCompressionFrameOptionsCreate
. If you passNULL
, nothing happens.
Discussion
If the retain count drops to 0, the object is disposed.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionFrameOptionsRetain
Increments the retain count of a frame compression options object.
ICMCompressionFrameOptionsRef ICMCompressionFrameOptionsRetain ( ICMCompressionFrameOptionsRef options );
Parameters
- options
A reference to a frame compression options object.This reference is returned by
ICMCompressionFrameOptionsCreate
. If you passNULL
, nothing happens.
Return Value
A copy of the object reference passed in options, for convenience.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionFrameOptionsSetForceKeyFrame
Forces frames to be compressed as key frames.
OSStatus ICMCompressionFrameOptionsSetForceKeyFrame ( ICMCompressionFrameOptionsRef options, Boolean forceKeyFrame );
Parameters
- options
A compression frame options reference. This reference is returned by
ICMCompressionFrameOptionsCreate
.- forceKeyFrame
Pass
TRUE
to force frames to be compressed as key frames,FALSE
otherwise.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
The compressor must obey this flag if set. By default it is
set FALSE
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionFrameOptionsSetFrameType
Requests a frame be compressed as a particular frame type.
OSStatus ICMCompressionFrameOptionsSetFrameType ( ICMCompressionFrameOptionsRef options, ICMFrameType frameType );
Parameters
- options
A compression frame options reference. This reference is returned by
ICMCompressionFrameOptionsCreate
.- frameType
A constant that identifies a frame type. Pass one of the following but do not assume that there are no other frame types:
kICMFrameType_I = 'I'
An I frame.
kICMFrameType_P = 'P'
A P frame.
kICMFrameType_B = 'B'
A B frame.
kICMFrameType_Unknown = 0
A frame of unknown type.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
The frame type setting may be ignored by the compressor if
it is not appropriate. By default it is set to kICMFrameType_Unknown
.
Do not assume that kICMFrameType_I
sets
a key frame; if you need a key frame, call ICMCompressionFrameOptionsSetForceKeyFrame
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionFrameOptionsSetProperty
Sets the value of a specific property of a compression frame options object.
OSStatus ICMCompressionFrameOptionsSetProperty ( ICMCompressionFrameOptionsRef options, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ConstComponentValuePtr inPropValueAddress );
Parameters
- options
A compression frame options reference. This reference is returned by
ICMCompressionFrameOptionsCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- inPropValueSize
The size of the property value to be set.
- inPropValueAddress
A pointer to the value of the property to be set.
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
ICMCompressionSessionBeginPass
Announces the start of a specific compression pass.
OSStatus ICMCompressionSessionBeginPass ( ICMCompressionSessionRef session, ICMCompressionPassModeFlags passModeFlags, UInt32 flags );
Parameters
- session
A compression session reference. This reference is returned by
ICMCompressionSessionCreate
.- passModeFlags
Flags that describe how the compressor should behave in this pass of multipass encoding:
kICMCompressionPassMode_OutputEncodedFrames = 1L<<0
Output encoded frames.
kICMCompressionPassMode_NoSourceFrames = 1L<<1
The client need not provide source frame buffers.
kICMCompressionPassMode_WriteToMultiPassStorage = 1L<<2
The compressor may write private data to multipass storage.
kICMCompressionPassMode_ReadFromMultiPassStorage = 1L<<3
The compressor may read private data from multipass storage.
- flags
Reserved. Set to 0.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
The source frames and frame options for each display time
should be the same across passes. During multipass compression,
valid displayTimeStamp values must
be passed to ICMCompressionSessionEncodeFrame
,
because they are used to index the compressor’s stored state.
During an analysis pass (kICMCompressionPassMode_WriteToMultiPassStorage
),
the compressor does not output encoded frames but records compressor-private
information for each frame. During repeated analysis passes and
the encoding pass (kICMCompressionPassMode_ReadFromMultiPassStorage
),
the compressor may refer to this information for other frames and
use it to improve encoding. During an encoding pass (kICMCompressionPassMode_OutputEncodedFrames
),
the compressor must output encoded frames. If the compressor sets
the kICMCompressionPassMode_NoSourceFrames
flag
for the pass, the client may pass NULL
pixel
buffers to ICMCompressionSessionEncodeFrame
.
By default, the ICM provides local storage that lasts only until the compression session is disposed. If the client provides custom multipass storage, passes may be performed at different times or on different machines; segments of each pass may even be distributed.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionCompleteFrames
Forces a compression session to complete encoding frames.
OSStatus ICMCompressionSessionCompleteFrames ( ICMCompressionSessionRef session, Boolean completeAllFrames, TimeValue64 completeUntilDisplayTimeStamp, TimeValue64 nextDisplayTimeStamp );
Parameters
- session
A reference to a video compression session, returned by a previous call to
ICMCompressionSessionCreate
.- completeAllFrames
Pass
TRUE
to direct the session to complete all pending frames.- completeUntilDisplayTimeStamp
A 64-bit time value that represents the display time up to which to complete frames. This value is ignored if completeAllFrames is
TRUE
.- nextDisplayTimeStamp
A 64-bit time value that represents the display time of the next frame that should be passed to
EncodeFrame
. This value is ignored unlessICMCompressionSessionOptionsSetDurationsNeeded
setTRUE
andkICMValidTime_DisplayDurationIsValid
was 0 in validTimeFlags in the last call toICMCompressionSessionEncodeFrame
.
Return Value
Returns an error code, or 0 if there is no error. The function may return before frames are completed if the encoded frame callback routine returns an error.
Discussion
Call this function to force a compression session to complete
encoding frames. Set completeAllFrames to
direct the session to complete all pending frames. If completeAllFrames is
false, only frames with display time stamps up to and including
the time passed in completeUntilDisplayTimeStamp will
be encoded. If ICMCompressionSessionOptionsSetDurationsNeeded
set TRUE
and
you are passing valid display timestamps but not display durations
to ICMCompressionSessionEncodeFrame
, pass
in nextDisplayTimeStamp the display
timestamp of the next frame that would be passed to EncodeFrame
.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionCreate
Creates a compression session for a specified codec type.
OSStatus ICMCompressionSessionCreate ( CFAllocatorRef allocator, int width, int height, CodecType cType, TimeScale timescale, ICMCompressionSessionOptionsRef compressionOptions, CFDictionaryRef sourcePixelBufferAttributes, ICMEncodedFrameOutputRecord *encodedFrameOutputRecord, ICMCompressionSessionRef *compressionSessionOut );
Parameters
- allocator
An allocator for the session. Pass
NULL
to use the default allocator.- width
The width of frames. Pass 0 to let the compressor control the width.
- height
The height of frames. Pass 0 to let the compressor control the height.
- cType
The codec type.
- timescale
The timescale to be used for all time stamps and durations used in the session.
- compressionOptions
A reference to a settings object that configures the session. You create such an object by calling
ICMCompressionSessionOptionsCreate
. You can then use these constants to set its properties:kICMUnlimitedFrameDelayCount
No limit on the number of frames in the compression window.
kICMUnlimitedFrameDelayTime
No time limit on the frames in the compression window.
kICMUnlimitedCPUTimeBudget
No CPU time limit on compression.
- sourcePixelBufferAttributes
Required attributes for source pixel buffers, used when creating a pixel buffer pool for source frames. If you do not want the ICM to create one for you, pass
NULL
. Using pixel buffers not allocated by the ICM may increase the chance that it will be necessary to copy image data.- encodedFrameOutputRecord
The callback that will receive encoded frames.
- compressionSessionOut
Points to a variable to receive the created session object.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
Some compressors do not support arbitrary source dimensions, and may override the suggested width and height.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionEncodeFrame
Presents video frames to a compression session.
OSStatus ICMCompressionSessionEncodeFrame ( ICMCompressionSessionRef session, CVPixelBufferRef pixelBuffer, TimeValue64 displayTimeStamp, TimeValue64 displayDuration, ICMValidTimeFlags validTimeFlags, ICMCompressionFrameOptionsRef frameOptions, ICMSourceTrackingCallbackRecord *sourceTrackingCallback, void *sourceFrameRefCon );
Parameters
- session
A reference to a video compression session, returned by a previous call to
ICMCompressionSessionCreate
.- pixelBuffer
A reference to a buffer containing a source image to be compressed, which must have a nonzero reference count. The session will retain it as long as necessary. The client should not modify the pixel buffer’s pixels until the pixel buffer release callback is called. In a multipass encoding session pass, where the compressor suggested the flag
kICMCompressionPassMode_NoSourceFrames
, you may passNULL
in this parameter.- displayTimeStamp
A 64-bit time value that represents the display time of the frame, using the time scale passed to
ICMCompressionSessionCreate
. If you pass a valid value, set thekICMValidTime_DisplayTimeStampIsValid
flag in the validTimeFlags parameter (below).- displayDuration
A 64-bit time value that represents the display duration of the frame, using the time scale passed to
ICMCompressionSessionCreate
. If you pass a valid value, set thekICMValidTime_DisplayDurationIsValid
flag in the validTimeFlags parameter (below).- validTimeFlags
Flags to indicate which of the values passed in displayTimeStamp and displayDuration are valid:
kICMValidTime_DisplayTimeStampIsValid
The time value passed in displayTimeStamp is valid.
kICMValidTime_DisplayDurationIsValid
The time value passed in displayDuration is valid.
- frameOptions
Options for this frame. Currently not used; pass
NULL
.- sourceTrackingCallback
A pointer to a callback to be notified about the status of this source frame. Pass
NULL
if you do not require notification.- sourceFrameRefCon
A reference constant to be passed to your callback. Use this parameter to point to a data structure containing any information your callback needs.
Return Value
Returns an error code, or 0 if there is no error. Encoded frames may or may not be output before the function returns.
Discussion
The session will retain the pixel buffer as long as necessary,
and the client should not modify the pixel data until the session
releases it. The most practical way to deal with this is by allocating
pixel buffers from a pool. The client may fill in both, either,
or neither of displayTimeStamp and displayDuration,
but should set the appropriate flags to indicate which are valid.
If the client needs to track the progress of a source frame, it
should provide a source tracking callback. If multipass compression
is enabled, calls to this function must be bracketed by calls to ICMCompressionSessionBeginPass
and ICMCompressionSessionEndPass
.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionEndPass
Announces the end of a pass.
OSStatus ICMCompressionSessionEndPass ( ICMCompressionSessionRef session );
Parameters
- session
A compression session reference. This reference is returned by
ICMCompressionSessionCreate
.
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
ICMCompressionSessionGetImageDescription
Retrieves the image description for a video compression session.
OSStatus ICMCompressionSessionGetImageDescription ( ICMCompressionSessionRef session, ImageDescriptionHandle *imageDescOut );
Parameters
- session
A reference to a video compression session, returned by a previous call to
ICMCompressionSessionCreate
.- imageDescOut
A handle to an
ImageDescription
structure. The caller must not dispose of this handle; the ICM will dispose of it when the compression session is disposed.
Return Value
Returns an error code, or 0 if there is no error. For some codecs, this function may fail if called before the first frame is compressed.
Discussion
Multiple calls to this function return the same handle.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionGetPixelBufferPool
Returns a pool that can provide ideal source pixel buffers for a compression session.
CVPixelBufferPoolRef ICMCompressionSessionGetPixelBufferPool ( ICMCompressionSessionRef session );
Parameters
- session
A compression session reference. This reference is returned by
ICMCompressionSessionCreate
.
Return Value
A reference to a pool
of pixel buffers. The compression session creates this pixel buffer
pool based on the compressor’s pixel buffer attributes and any pixel
buffer attributes passed to ICMCompressionSessionCreate
.
Discussion
A new compression session builds this pixel buffer pool based
on the compressor’s pixel buffer attributes and any pixel buffer
attributes passed in to ICMCompressionSessionCreate
.
If the source pixel buffer attributes and the compressor pixel buffer
attributes cannot be reconciled, the pool is based on the source
pixel buffer attributes and the ICM converts each pixel buffer internally.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionGetProperty
Retrieves the value of a specific property of a compression session.
OSStatus ICMCompressionSessionGetProperty ( ICMCompressionSessionRef session, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ComponentValuePtr outPropValueAddress, ByteCount *outPropValueSizeUsed );
Parameters
- session
A compression session reference. This reference is returned by
ICMCompressionSessionCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueAddress
A pointer to a variable to receive the returned property’s value.
- outPropValueSizeUsed
On return, a pointer to the number of bytes actually used to store the property.
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
ICMCompressionSessionGetPropertyInfo
Retrieves information about properties of a compression session.
OSStatus ICMCompressionSessionGetPropertyInfo ( ICMCompressionSessionRef session, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ComponentValueType *outPropType, ByteCount *outPropValueSize, UInt32 *outPropertyFlags );
Parameters
- session
A compression session reference. This reference is returned by
ICMCompressionSessionCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueSize
A pointer to the size of the returned property’s value.
- outPropFlags
On return, a pointer to flags representing the requested information about the property.
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
ICMCompressionSessionGetTimeScale
Retrieves the time scale for a compression session.
TimeScale ICMCompressionSessionGetTimeScale ( ICMCompressionSessionRef session );
Parameters
- session
A compression session reference. This reference is returned by
ICMCompressionSessionCreate
.
Return Value
The time scale for the compression session.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionGetTypeID
Returns the type ID for the current compression session.
CFTypeID ICMCompressionSessionGetTypeID ( void );
Return Value
A CFTypeID
value.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsCreate
Creates a compression session options object.
OSStatus ICMCompressionSessionOptionsCreate ( CFAllocatorRef allocator, ICMCompressionSessionOptionsRef *options );
Parameters
- allocator
An allocator. Pass
NULL
to use the default allocator.- options
On return, a reference to a new compression session options object.
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
ICMCompressionSessionOptionsCreateCopy
Copies a compression session options object.
OSStatus ICMCompressionSessionOptionsCreateCopy ( CFAllocatorRef allocator, ICMCompressionSessionOptionsRef originalOptions, ICMCompressionSessionOptionsRef *copiedOptions );
Parameters
- allocator
An allocator. Pass
NULL
to use the default allocator.- originalOptions
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.- copiedOptions
On return, a reference to a copy of the compression session options object passed in originalOptions.
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
ICMCompressionSessionOptionsGetAllowFrameReordering
Retrieves the allow frame reordering flag.
Boolean ICMCompressionSessionOptionsGetAllowFrameReordering ( ICMCompressionSessionOptionsRef options );
Parameters
- options
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.
Return Value
Returns TRUE
if
frame reordering is allowed, FALSE
otherwise.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsGetAllowFrameTimeChanges
Retrieves the allow frame time changes flag.
Boolean ICMCompressionSessionOptionsGetAllowFrameTimeChanges ( ICMCompressionSessionOptionsRef options );
Parameters
- options
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.
Return Value
Returns TRUE
if
the compressor is allowed to modify frame times, FALSE
otherwise.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsGetAllowTemporalCompression
Retrieves the allow temporal compression flag.
Boolean ICMCompressionSessionOptionsGetAllowTemporalCompression ( ICMCompressionSessionOptionsRef options );
Parameters
- options
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.
Return Value
Returns TRUE
if
temporal compression is allowed, FALSE
otherwise.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsGetDurationsNeeded
Retrieves the durations needed flag.
Boolean ICMCompressionSessionOptionsGetDurationsNeeded ( ICMCompressionSessionOptionsRef options );
Parameters
- options
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.
Return Value
Returns TRUE
if
the durations of outputted frames must be calculated, FALSE
otherwise.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsGetMaxKeyFrameInterval
Retrieves the maximum key frame interval.
SInt32 ICMCompressionSessionOptionsGetMaxKeyFrameInterval ( ICMCompressionSessionOptionsRef options );
Parameters
- options
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.
Return Value
Returns the maximum key frame interval.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsGetProperty
Retrieves the value of a specific property of a compression session options object.
OSStatus ICMCompressionSessionOptionsGetProperty ( ICMCompressionSessionOptionsRef options, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ComponentValuePtr outPropValueAddress, ByteCount *outPropValueSizeUsed );
Parameters
- options
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueAddress
A pointer to a variable to receive the returned property’s value.
- outPropValueSizeUsed
On return, a pointer to the number of bytes actually used to store the property.
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
ICMCompressionSessionOptionsGetPropertyInfo
Retrieves information about properties of a compression session options object.
OSStatus ICMCompressionSessionOptionsGetPropertyInfo ( ICMCompressionSessionOptionsRef options, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ComponentValueType *outPropType, ByteCount *outPropValueSize, UInt32 *outPropertyFlags );
Parameters
- options
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueSize
A pointer to the size of the returned property’s value.
- outPropFlags
On return, a pointer to flags representing the requested information about the property.
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
ICMCompressionSessionOptionsGetTypeID
Returns the type ID for the current compression session options object.
CFTypeID ICMCompressionSessionOptionsGetTypeID ( void );
Return Value
A CFTypeID
value.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsRelease
Decrements the retain count of a compression session options object.
void ICMCompressionSessionOptionsRelease ( ICMCompressionSessionOptionsRef options );
Parameters
- options
A reference to a compression session options object. This reference is returned by
ICMCompressionSessionOptionsCreate
. If you passNULL
, nothing happens.
Discussion
If the retain count drops to 0, the object is disposed.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsRetain
Increments the retain count of a compression session options object.
ICMCompressionSessionOptionsRef ICMCompressionSessionOptionsRetain ( ICMCompressionSessionOptionsRef options );
Parameters
- options
A reference to a compression session options object. This reference is returned by
ICMCompressionSessionOptionsCreate
. If you passNULL
, nothing happens.
Return Value
A copy of the object reference passed in options, for convenience.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsSetAllowFrameReordering
Enables frame reordering.
OSStatus ICMCompressionSessionOptionsSetAllowFrameReordering ( ICMCompressionSessionOptionsRef options, Boolean allowFrameReordering );
Parameters
- options
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.- allowFrameReordering
Pass
TRUE
to enable frame reordering,FALSE
to disable it.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
To encode B-frames a compressor must reorder frames, which
means that the order in which they will be emitted and stored (the
decode order) is different from the order in which they were presented
to the compressor (the display order). By default, frame reordering
is disabled. To encode using B-frames, you must call this function,
passing TRUE
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsSetAllowFrameTimeChanges
Allows the compressor to modify frame times.
OSStatus ICMCompressionSessionOptionsSetAllowFrameTimeChanges ( ICMCompressionSessionOptionsRef options, Boolean allowFrameTimeChanges );
Parameters
- options
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.- allowFrameTimeChanges
Pass
TRUE
to let the compressor to modify frame times,FALSE
to prohibit it.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
Some compressors are able to identify and coalesce runs of identical frames and output single frames with longer durations, or output frames at a different frame rate from the original. This feature is controlled by the allow frame time changes flag. By default, this flag is set to false, which forces compressors to emit one encoded frame for every source frame and preserve frame display times.
This function replaces the practice of having compressors return special high similarity values to indicate that frames could be dropped.
If you want to let the compressor modify frame times in order to improve compression performance, you should allow frame time changes.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsSetAllowTemporalCompression
Enables temporal compression.
OSStatus ICMCompressionSessionOptionsSetAllowTemporalCompression ( ICMCompressionSessionOptionsRef options, Boolean allowTemporalCompression );
Parameters
- options
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.- allowTemporalCompression
Pass
TRUE
to enable temporal compression,FALSE
to disable it.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
By default, temporal compression is disabled. If you want
temporal compression for P-frames or B-frames you must call this
function and pass TRUE
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsSetDurationsNeeded
Indicates that the durations of outputted frames must be calculated.
OSStatus ICMCompressionSessionOptionsSetDurationsNeeded ( ICMCompressionSessionOptionsRef options, Boolean decodeDurationsNeeded );
Parameters
- options
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.- decodeDurationsNeeded
Pass
TRUE
to indicate that durations must be calculated,FALSE
otherwise.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
If this flag is set and source frames are provided with times but not durations, then frames will be delayed so that durations can be calculated as the difference between one frame’s time stamp and the next frame’s time stamp. By default this flag is 0, so frames will not be delayed in order to calculate durations.
If you are passing encoded frames to AddMediaSampleFromEncodedFrame
,
you must call this function and pass TRUE
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsSetMaxKeyFrameInterval
Sets the maximum interval between key frames.
OSStatus ICMCompressionSessionOptionsSetMaxKeyFrameInterval ( ICMCompressionSessionOptionsRef options, SInt32 maxKeyFrameInterval );
Parameters
- options
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.- maxKeyFrameInterval
The maximum interval between key frames, also known as the key frame rate.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
Compressors are allowed to generate key frames more frequently if this would result in more efficient compression. The default key frame interval is 0, which indicates that the compressor should choose where to place all key frames.
This is a break with previous practice, which used a key frame rate of 0 to disable temporal compression.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionOptionsSetProperty
Sets the value of a specific property of a compression session options object.
OSStatus ICMCompressionSessionOptionsSetProperty ( ICMCompressionSessionOptionsRef options, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ConstComponentValuePtr inPropValueAddress );
Parameters
- options
A compression session options reference. This reference is returned by
ICMCompressionSessionOptionsCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- inPropValueSize
The size of the property value to be set.
- inPropValueAddress
A pointer to the value of the property to be set.
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
ICMCompressionSessionProcessBetweenPasses
Lets the compressor perform processing between passes.
OSStatus ICMCompressionSessionProcessBetweenPasses ( ICMCompressionSessionRef session, UInt32 flags, Boolean *interpassProcessingDoneOut, ICMCompressionPassModeFlags *requestedNextPassModeFlagsOut );
Parameters
- session
A compression session reference. This reference is returned by
ICMCompressionSessionCreate
.- flags
Reserved. Set to 0.
- interpassProcessingDoneOut
A pointer to a
Boolean
that will be set toFALSE
if this function should be called again,TRUE
if not.- requestedNextPassModeFlagsOut
A pointer to
ICMCompressionPassModeFlags
that will be set to the codec’s recommended mode flags for the next pass.kICMCompressionPassMode_OutputEncodedFrames
will be set only if it recommends that the next pass be the final one:kICMCompressionPassMode_OutputEncodedFrames = 1L<<0
Output encoded frames.
kICMCompressionPassMode_NoSourceFrames = 1L<<1
The client need not provide source frame buffers.
kICMCompressionPassMode_WriteToMultiPassStorage = 1L<<2
The compressor may write private data to multipass storage.
kICMCompressionPassMode_ReadFromMultiPassStorage = 1L<<3
The compressor may read private data from multipass storage.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
Call this function repeatedly until the compressor sets interpassProcessingDoneOut to TRUE
to
indicate that it is done with this round of interpass processing.
When done, the compressor will indicate its preferred mode for the
next pass. At this point the client may choose to begin an encoding
pass, by OR-combining the kICMCompressionPassMode_OutputEncodedFrames
flag,
regardless of the compressor’s request.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionRelease
Decrements the retain count of a compression session.
void ICMCompressionSessionRelease ( ICMCompressionSessionRef session );
Parameters
- session
A compression session reference. This reference is returned by
ICMCompressionSessionCreate
. If you passNULL
, nothing happens.
Discussion
If the retain count drops to 0, the session is disposed.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionRetain
Increments the retain count of a compression session.
ICMCompressionSessionRef ICMCompressionSessionRetain ( ICMCompressionSessionRef session );
Parameters
- session
A compression session reference. This reference is returned by
ICMCompressionSessionCreate
. If you passNULL
, nothing happens.
Return Value
A reference to the object passed in session, for convenience.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressionSessionSetProperty
Sets the value of a specific property of a compression session.
OSStatus ICMCompressionSessionSetProperty ( ICMCompressionSessionRef session, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ConstComponentValuePtr inPropValueAddress );
Parameters
- session
A compression session reference. This reference is returned by
ICMCompressionSessionCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- inPropValueSize
The size of the property value to be set.
- inPropValueAddress
A pointer to the value of the property to be set.
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
ICMCompressionSessionSupportsMultiPassEncoding
Queries whether a compression session supports multipass encoding.
Boolean ICMCompressionSessionSupportsMultiPassEncoding ( ICMCompressionSessionRef session, UInt32 multiPassStyleFlags, ICMCompressionPassModeFlags *firstPassModeFlagsOut );
Parameters
- session
A compression session reference. This reference is returned by
ICMCompressionSessionCreate
.- multiPassStyleFlags
Reserved; set to 0.
- firstPassModeFlagsOut
A pointer to a variable to receive the session’s requested mode flags for the first pass. The client may modify these flags, but should not set
kICMCompressionPassMode_NoSourceFrames
. PassNULL
if you do not want this information.
Return Value
Returns TRUE
if
the compression session supports multipass encoding, FALSE
otherwise.
Discussion
Even if this function returns FALSE
,
if you passed TRUE
to ICMCompressionSessionOptionsSetMultiPass
,
you must call ICMCompressionSessionBeginPass
and ICMCompressionSessionEndPass
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressorSessionDropFrame
Called by a compressor to notify the ICM that a source frame has been dropped and will not contribute to any encoded frames.
OSStatus ICMCompressorSessionDropFrame ( ICMCompressorSessionRef session, ICMCompressorSourceFrameRef sourceFrame );
Parameters
- session
A reference to the compression session between the ICM and an image compressor component.
- sourceFrame
A reference to a frame that has been passed in sourceFrameRefCon to
ICMCompressionSessionEncodeFrame
. If you passNULL
, nothing happens.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
Calling this function does not automatically release the source
frame; if the compressor called ICMCompressorSourceFrameRetain
it
should still call ICMCompressorSourceFrameRelease
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressorSessionEmitEncodedFrame
Called by a compressor to output an encoded frame corresponding to one or more source frames.
OSStatus ICMCompressorSessionEmitEncodedFrame ( ICMCompressorSessionRef session, ICMMutableEncodedFrameRef encodedFrame, long numberOfSourceFrames, ICMCompressorSourceFrameRef sourceFrames[] );
Parameters
- session
A reference to the compression session between the ICM and an image compressor component.
- encodedFrame
A reference to an encoded frame object with write capabilities.
- numberOfSourceFrames
The number of source frames encoded in the encoded frame.
- sourceFrames
References to frames that have been passed in sourceFrameRefCon to
ICMCompressionSessionEncodeFrame
.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
Encoded frames may correspond to more than one source frame
only if allowFrameTimeChanges
is
set in the compression session’s compressionSessionOptions
.
After calling this function, the compressor should release
the encoded frame by calling ICMEncodedFrameRelease
.
Calling this function does not automatically release the source frames;
if the compressor called ICMCompressorSourceFrameRetain
it
should still call ICMCompressorSourceFrameRelease
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressorSourceFrameGetDisplayNumber
Retrieves a source frames display number.
long ICMCompressorSourceFrameGetDisplayNumber ( ICMCompressorSourceFrameRef sourceFrame );
Parameters
- sourceFrame
A reference to a frame that has been passed in sourceFrameRefCon to
ICMCompressionSessionEncodeFrame
.
Return Value
The display number of the source frame.
Discussion
The ICM tags source frames with display numbers in the order
that they are passed to ICMCompressionSessionEncodeFrame
.
The first display number is 1. Compressors may compare these numbers
to work out whether prediction is forward or backward, even when
display times are not provided.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressorSourceFrameGetDisplayTimeStampAndDuration
Retrieves the display time stamp and duration of a source frame.
OSStatus ICMCompressorSourceFrameGetDisplayTimeStampAndDuration ( ICMCompressorSourceFrameRef sourceFrame, TimeValue64 *displayTimeStampOut, TimeValue64 *displayDurationOut, TimeScale *timeScaleOut, ICMValidTimeFlags *validTimeFlagsOut );
Parameters
- sourceFrame
A reference to a frame that has been passed in sourceFrameRefCon to
ICMCompressionSessionEncodeFrame
.- displayTimeStampOut
A pointer to the source frame’s display time stamp.
- displayDurationOut
A pointer to the source frame’s display duration.
- timeScaleOut
A pointer to the source frame’s display time scale.
- validTimeFlagsOut
A pointer to one of these display time flags for the source frame:
kICMValidTime_DisplayTimeStampIsValid = 1L<<0
The value of displayTimeStamp is valid.
kICMValidTime_DisplayDurationIsValid = 1L<<1
The value of displayDuration is valid.
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
ICMCompressorSourceFrameGetFrameOptions
Retrieves the frame compression options for a source frame.
ICMCompressionFrameOptionsRef ICMCompressorSourceFrameGetFrameOptions ( ICMCompressorSourceFrameRef sourceFrame );
Parameters
- sourceFrame
A reference to a frame that has been passed in sourceFrameRefCon to
ICMCompressionSessionEncodeFrame
.
Return Value
A compression session
frame options reference representing options for this frame. A frame
options object is created by ICMCompressionFrameOptionsCreate
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressorSourceFrameGetPixelBuffer
Retrieves a source frames pixel buffer.
CVPixelBufferRef ICMCompressorSourceFrameGetPixelBuffer ( ICMCompressorSourceFrameRef sourceFrame );
Parameters
- sourceFrame
A reference to a frame that has been passed in sourceFrameRefCon to
ICMCompressionSessionEncodeFrame
.
Return Value
A reference to the pixel buffer containing the source frame’s image being compressed.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressorSourceFrameGetTypeID
Returns the type ID for the current source frame object.
CFTypeID ICMCompressorSourceFrameGetTypeID ( void );
Return Value
A CFTypeID
value.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressorSourceFrameRelease
Decrements the retain count of a source frame object.
void ICMCompressorSourceFrameRelease ( ICMCompressorSourceFrameRef sourceFrame );
Parameters
- sourceFrame
A reference to a frame that has been passed in sourceFrameRefCon to
ICMCompressionSessionEncodeFrame
. If you passNULL
, nothing happens.
Discussion
If the retain count drops to 0, the object is disposed.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMCompressorSourceFrameRetain
Increments the retain count of a source frame object.
ICMCompressorSourceFrameRef ICMCompressorSourceFrameRetain ( ICMCompressorSourceFrameRef sourceFrame );
Parameters
- sourceFrame
A reference to a frame that has been passed in sourceFrameRefCon to
ICMCompressionSessionEncodeFrame
. If you passNULL
, nothing happens.
Return Value
A reference to the object passed in sourceFrame, for convenience.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionFrameOptionsCreate
Creates a frame decompression options object.
OSStatus ICMDecompressionFrameOptionsCreate ( CFAllocatorRef allocator, ICMDecompressionFrameOptionsRef *options );
Parameters
- allocator
An allocator. Pass
NULL
to use the default allocator.- options
On return, a reference to a frame decompression options object.
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
ICMDecompressionFrameOptionsCreateCopy
Copies a frame decompression options object.
OSStatus ICMDecompressionFrameOptionsCreateCopy ( CFAllocatorRef allocator, ICMDecompressionFrameOptionsRef originalOptions, ICMDecompressionFrameOptionsRef *copiedOptions );
Parameters
- allocator
An allocator. Pass
NULL
to use the default allocator.- originalOptions
A reference to a frame decompression options object. You can create this object by calling
ICMDecompressionFrameOptionsCreate
.- copiedOptions
On return, a reference to a copy of the frame decompression options object passed in originalOptions.
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
ICMDecompressionFrameOptionsGetProperty
Retrieves the value of a specific property of a decompression frame options object.
OSStatus ICMDecompressionFrameOptionsGetProperty ( ICMDecompressionFrameOptionsRef options, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ComponentValuePtr outPropValueAddress, ByteCount *outPropValueSizeUsed );
Parameters
- options
A decompression frame options reference. This reference is returned by
ICMDecompressionFrameOptionsCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueAddress
A pointer to a variable to receive the returned property’s value.
- outPropValueSizeUsed
On return, a pointer to the number of bytes actually used to store the property.
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
ICMDecompressionFrameOptionsGetPropertyInfo
Retrieves information about properties of a decompression frame options object.
OSStatus ICMDecompressionFrameOptionsGetPropertyInfo ( ICMDecompressionFrameOptionsRef options, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ComponentValueType *outPropType, ByteCount *outPropValueSize, UInt32 *outPropertyFlags );
Parameters
- options
A decompression frame options reference. This reference is returned by
ICMDecompressionFrameOptionsCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueSize
A pointer to the size of the returned property’s value.
- outPropFlags
On return, a pointer to flags representing the requested information about the frame option’s property.
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
ICMDecompressionFrameOptionsGetTypeID
Returns the type ID for the current frame decompression options object.
CFTypeID ICMDecompressionFrameOptionsGetTypeID ( void );
Return Value
A CFTypeID
value.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionFrameOptionsRelease
Decrements the retain count of a frame decompression options object.
void ICMDecompressionFrameOptionsRelease ( ICMDecompressionFrameOptionsRef options );
Parameters
- options
A reference to a frame decompression options object. You can create this object by calling
ICMDecompressionFrameOptionsCreate
. If you passNULL
, nothing happens.
Discussion
If the retain count drops to 0, the object is disposed.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionFrameOptionsRetain
Increments the retain count of a frame decompression options object.
ICMDecompressionFrameOptionsRef ICMDecompressionFrameOptionsRetain ( ICMDecompressionFrameOptionsRef options );
Parameters
- options
A reference to a frame decompression options object. You can create this object by calling
ICMDecompressionFrameOptionsCreate
. If you passNULL
, nothing happens.
Return Value
A reference to the frame decompression options object passed in options, for convenience.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionFrameOptionsSetProperty
Sets the value of a specific property of a decompression frame options object.
OSStatus ICMDecompressionFrameOptionsSetProperty ( ICMDecompressionFrameOptionsRef options, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ConstComponentValuePtr inPropValueAddress );
Parameters
- options
A decompression frame options reference. This reference is returned by
ICMDecompressionFrameOptionsCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- inPropValueSize
The size of the property value to be set.
- inPropValueAddress
A pointer to the value of the property to be set.
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
ICMDecompressionSessionCreate
Creates a session for decompressing video frames.
OSStatus ICMDecompressionSessionCreate ( CFAllocatorRef allocator, ImageDescriptionHandle desc, ICMDecompressionSessionOptionsRef decompressionOptions, CFDictionaryRef destinationPixelBufferAttributes, ICMDecompressionTrackingCallbackRecord *trackingCallback, ICMDecompressionSessionRef *decompressionSessionOut );
Parameters
- allocator
An allocator for the session. Pass
NULL
to use the default allocator.- desc
An image description for the source frames.
- decompressionOptions
A decompression session options reference. This reference is returned by
ICMDecompressionSessionOptionsCreate
. The session will retain the object. You may change some options during the session by modifying the object. You may also passNULL
.- destinationPixelBufferAttributes
Requirements for emitted pixel buffers. You may pass
NULL
.- trackingCallback
A pointer to a structure that designates a callback to be called for information about queued frames and pixel buffers containing decompressed frames. See
ICMDecompressionTrackingCallbackRecord
andICMDecompressionTrackingCallbackProc
.- decompressionSessionOut
A pointer to a variable to receive a reference to the new decompression session.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
Frames are returned through calls to the callback pointed
to by trackingCallback
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionSessionCreateForVisualContext
Creates a session for decompressing video frames.
OSStatus ICMDecompressionSessionCreateForVisualContext ( CFAllocatorRef allocator, /*can be NULL */ ImageDescriptionHandle desc, ICMDecompressionSessionOptionsRef decompressionOptions, /*can be NULL */ QTVisualContextRef visualContext, ICMDecompressionTrackingCallbackRecord *trackingCallback, ICMDecompressionSessionRef *decompressionSessionOut );
Parameters
- allocator
An allocator for the session. Pass
NULL
to use the default allocator.- desc
An image description for the source frames.
- decompressionOptions
Options for the session. The session will retain this options object. You may change some options during the session by modifying the object.
- visualContext
The target visual context.
- trackingCallback
The callback to be called with information about queued frames, and pixel buffers containing the decompressed frames.
- decompressionSessionOut
Points to a variable to receive the new decompression session.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
Frames will be output to a visual context. If desired, the trackingCallback may attach additional data to pixel buffers before they are sent to the visual context.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionSessionDecodeFrame
Queues a frame for decompression.
OSStatus ICMDecompressionSessionDecodeFrame ( ICMDecompressionSessionRef session, const UInt8 *data, ByteCount dataSize, ICMDecompressionFrameOptionsRef frameOptions, const ICMFrameTimeRecord *frameTime, void *sourceFrameRefCon );
Parameters
- session
A decompression session reference. This reference is returned by
ICMDecompressionSessionCreate
.- data
A pointer to the compressed data for this frame. The data must remain in this location until
ICMDecompressionTrackingCallbackProc
is called with thekICMDecompressionTracking_ReleaseSourceData
flag set in decompressionTrackingFlags.- dataSize
The number of bytes of compressed data. You may not pass 0 in this parameter.
- frameOptions
A reference to a frame decompression options object containing options for this frame. You can create this object by calling
ICMDecompressionFrameOptionsCreate
.- frameTime
A pointer to a structure describing the frame’s timing information.
- sourceFrameRefCon
Your reference value for the frame.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionSessionFlush
Flushes the frames queued for a decompression session.
OSStatus ICMDecompressionSessionFlush ( ICMDecompressionSessionRef session );
Parameters
- session
A decompression session reference. This reference is returned by
ICMDecompressionSessionCreate
.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
The tracking callback will be called for each frame with the result –1.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionSessionGetProperty
Retrieves the value of a specific property of a decompression session.
OSStatus ICMDecompressionSessionGetProperty ( ICMDecompressionSessionRef session, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ComponentValuePtr outPropValueAddress, ByteCount *outPropValueSizeUsed );
Parameters
- session
A decompression session reference. This reference is returned by
ICMDecompressionSessionCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueAddress
A pointer to a variable to receive the returned property’s value.
- outPropValueSizeUsed
On return, a pointer to the number of bytes actually used to store the property.
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
ICMDecompressionSessionGetPropertyInfo
Retrieves information about the properties of a decompression session.
OSStatus ICMDecompressionSessionGetPropertyInfo ( ICMDecompressionSessionRef session, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ComponentValueType *outPropType, ByteCount *outPropValueSize, UInt32 *outPropertyFlags );
Parameters
- session
A decompression session reference. This reference is returned by
ICMDecompressionSessionCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueSize
A pointer to the size of the returned property’s value.
- outPropFlags
On return, a pointer to flags representing the requested information about the property.
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
ICMDecompressionSessionGetTypeID
Returns the type ID for the current decompression session.
CFTypeID ICMDecompressionSessionGetTypeID ( void );
Return Value
A CFTypeID
value.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionSessionOptionsCreate
Creates a decompression session options object.
OSStatus ICMDecompressionSessionOptionsCreate ( CFAllocatorRef allocator, ICMDecompressionSessionOptionsRef *options );
Parameters
- allocator
An allocator. Pass
NULL
to use the default allocator.- options
On return, a reference to a decompression session options object.
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
ICMDecompressionSessionOptionsCreateCopy
Copies a decompression session options object.
OSStatus ICMDecompressionSessionOptionsCreateCopy ( CFAllocatorRef allocator, ICMDecompressionSessionOptionsRef originalOptions, ICMDecompressionSessionOptionsRef *copiedOptions );
Parameters
- allocator
An allocator. Pass
NULL
to use the default allocator.- originalOptions
A decompression session options reference. This reference is returned by
ICMDecompressionSessionOptionsCreate
.- copiedOptions
On return, a reference to a copy of the decompression session options object passed in originalOptions.
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
ICMDecompressionSessionOptionsGetPropertyInfo
Retrieves information about properties of a decompression session options object.
OSStatus ICMDecompressionSessionOptionsGetPropertyInfo ( ICMDecompressionSessionOptionsRef options, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ComponentValueType *outPropType, ByteCount *outPropValueSize, UInt32 *outPropertyFlags );
Parameters
- options
A decompression session options reference. This reference is returned by
ICMDecompressionSessionOptionsCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueSize
A pointer to the size of the returned property’s value.
- outPropFlags
On return, a pointer to flags representing the requested information about the property.
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
ICMDecompressionSessionOptionsGetProperty
Retrieves the value of a specific property of a decompression session options object.
OSStatus ICMDecompressionSessionOptionsGetProperty ( ICMDecompressionSessionOptionsRef options, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ComponentValuePtr outPropValueAddress, ByteCount *outPropValueSizeUsed );
Parameters
- options
A decompression session options reference. This reference is returned by
ICMDecompressionSessionOptionsCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- inPropValueSize
The size of the property value to be retrieved.
- outPropValueAddress
A pointer to a variable to hold the value of the property.
- outPropValueSizeUsed
On return, a pointer to the number of bytes actually used to store the property value.
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
ICMDecompressionSessionOptionsGetTypeID
Returns the type ID for the current decompression session options object.
CFTypeID ICMDecompressionSessionOptionsGetTypeID ( void );
Return Value
A CFTypeID
value.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionSessionOptionsRelease
Decrements the retain count of a decompression session options object.
void ICMDecompressionSessionOptionsRelease ( ICMDecompressionSessionOptionsRef options );
Parameters
- options
A reference to a decompression session options object. This reference is returned by
ICMDecompressionSessionOptionsCreate
. If you passNULL
, nothing happens.
Discussion
If the retain count drops to 0, the object is disposed.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionSessionOptionsRetain
Increments the retain count of a decompression session options object.
ICMDecompressionSessionOptionsRef ICMDecompressionSessionOptionsRetain ( ICMDecompressionSessionOptionsRef options );
Parameters
- options
A reference to a decompression session options object. This reference is returned by
ICMDecompressionSessionOptionsCreate
. If you passNULL
, nothing happens.
Return Value
A copy of the object reference passed in options, for convenience.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionSessionOptionsSetProperty
Sets the value of a specific property of a decompression session options object.
OSStatus ICMDecompressionSessionOptionsSetProperty ( ICMDecompressionSessionOptionsRef options, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ConstComponentValuePtr inPropValueAddress );
Parameters
- options
A decompression session options reference. This reference is returned by
ICMDecompressionSessionOptionsCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- inPropValueSize
The size of the property value to be set.
- inPropValueAddress
A pointer to the value of the property to be set.
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
ICMDecompressionSessionRetain
Increments the retain count of a decompression session.
ICMDecompressionSessionRef ICMDecompressionSessionRetain ( ICMDecompressionSessionRef session );
Parameters
- session
A decompression session reference. This reference is returned by
ICMDecompressionSessionCreate
. If you passNULL
, nothing happens.
Return Value
A copy of the reference passed in session, for convenience.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionSessionRelease
Decrements the retain count of a decompression session.
void ICMDecompressionSessionRelease ( ICMDecompressionSessionRef session );
Parameters
- session
A decompression session reference. This reference is returned by
ICMDecompressionSessionCreate
. If you passNULL
, nothing happens.
Discussion
If the retain count drops to 0, the object is disposed.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMDecompressionSessionSetNonScheduledDisplayDirection
Sets the direction for non-scheduled display time.
OSStatus ICMDecompressionSessionSetNonScheduledDisplayDirection ( ICMDecompressionSessionRef session, Fixed rate );
Parameters
- session
A decompression session reference. This reference is returned by
ICMDecompressionSessionCreate
.- rate
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
ICMDecompressionSessionSetNonScheduledDisplayTime
Sets the display time for a decompression session, and requests display of the non-scheduled queued frame at that display time, if there is one.
OSStatus ICMDecompressionSessionSetNonScheduledDisplayTime ( ICMDecompressionSessionRef session, TimeValue64 displayTime, TimeScale displayTimeScale, UInt32 flags );
Parameters
- session
A decompression session reference. This reference is returned by
ICMDecompressionSessionCreate
.- displayTime
A display time. Usually this is the display time of a non-scheduled queued frame.
- displayTimeScale
The timescale according to which displayTime should be interpreted.
- flags
Reserved; set to 0.
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
ICMDecompressionSessionSetProperty
Sets the value of a specific property of a decompression session.
OSStatus ICMDecompressionSessionSetProperty ( ICMDecompressionSessionRef session, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ConstComponentValuePtr inPropValueAddress );
Parameters
- session
A decompression session reference. This reference is returned by
ICMDecompressionSessionCreate
.- inPropClass
Pass the following constant to define the property class:
kComponentPropertyClassPropertyInfo = 'pnfo'
The property information class.
- inPropID
Pass one of these constants to define the property ID:
kComponentPropertyInfoList = 'list'
An array of
CFData
values, one for each property.kComponentPropertyCacheSeed = 'seed'
A property cache seed value.
kComponentPropertyCacheFlags = 'flgs'
One of the
kComponentPropertyCache
flags:kComponentPropertyCacheFlagNotPersistent
Property metadata should not be saved in persistent cache.
kComponentPropertyCacheFlagIsDynamic
Property metadata should not cached at all.
kComponentPropertyExtendedInfo = 'meta'
A
CFDictionary
with extended property information.
- inPropValueSize
The size in bytes of the property’s value.
- inPropValueAddress
A pointer to the property value to be set.
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
ICMEncodedFrameGetBufferSize
Gets the size of an encoded frame’s data buffer.
ByteCount ICMEncodedFrameGetBufferSize ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
The physical size in bytes of the encoded frame’s data buffer.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameCreateMutable
Called by a compressor to create an encoded-frame token corresponding to a given source frame.
OSStatus ICMEncodedFrameCreateMutable ( ICMCompressorSessionRef session, ICMCompressorSourceFrameRef sourceFrame, ByteCount bufferSize, ICMMutableEncodedFrameRef *frameOut );
Parameters
- session
A reference to the compression session between the ICM and an image compressor component.
- sourceFrame
A reference to a frame that has been passed in sourceFrameRefCon to
ICMCompressionSessionEncodeFrame
.- bufferSize
The size of the frame buffer in bytes.
- frameOut
On return, a reference to an encoded frame object with write capabilities.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
The encoded frame will initially show 0 for mediaSampleFlags
;
if the frame is not a key frame, the compressor must call ICMEncodedFrameSetMediaSampleFlags
to
set mediaSampleNotSync
.
If the frame is droppable, the compressor should set mediaSampleDroppable
.
If the frame is a partial key frame, the compressor should set mediaSamplePartialSync
.
The encoded frame will initially have undefined decodeTimeStamp
and decodeDuration
values.
The compressor may set these directly by calling ICMEncodedFrameSetDecodeTimeStamp
and ICMEncodedFrameSetDecodeDuration
.
If these are not set by the compressor, the ICM will try to derive
values for them.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetDataPtr
Gets the data buffer for an encoded frame.
UInt8 *ICMEncodedFrameGetDataPtr ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
A pointer to the object’s data buffer.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetDataSize
Gets the data size of the compressed frame in an encoded frame’s buffer.
ByteCount ICMEncodedFrameGetDataSize ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
The logical size in bytes of the encoded frame’s data buffer, which may be less than the physical size of the buffer.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetDecodeDuration
Retrieves an encoded frame’s decode duration.
TimeValue64 ICMEncodedFrameGetDecodeDuration ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
The encoded frame’s decode duration.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetDecodeNumber
Retrieves the decode number of an encoded frame.
UInt32 ICMEncodedFrameGetDecodeNumber ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
The decode number of the encoded frame.
Discussion
The ICM automatically stamps ascending decode numbers on frames after the compressor emits them. The first decode number in session is 1. Compressors should not call this function.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetDecodeTimeStamp
Retrieves an encoded frame’s decode time stamp.
TimeValue64 ICMEncodedFrameGetDecodeTimeStamp ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
The encoded frame’s decode time stamp.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetDisplayDuration
Retrieves an encoded frame’s display duration.
TimeValue64 ICMEncodedFrameGetDisplayDuration ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
The encoded frame’s display duration.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetDisplayOffset
Retrieves an encoded frame’s display offset.
TimeValue64 ICMEncodedFrameGetDisplayOffset ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
The encoded frame’s display offset. This is the time offset from decode time stamp to display time stamp.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetDisplayTimeStamp
Retrieves an encoded frame’s display time stamp.
TimeValue64 ICMEncodedFrameGetDisplayTimeStamp ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
The encoded frame’s display time stamp.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetFrameType
Retrieves the frame
type
for an encoded frame.
ICMFrameType ICMEncodedFrameGetFrameType ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
The encoded frame’s frame type (see below).
Discussion
This function returns one of these values:
kICMFrameType_I = 'I'
An I frame.
kICMFrameType_P = 'P'
A P frame.
kICMFrameType_B = 'B'
A B frame.
kICMFrameType_Unknown = 0
A frame of unknown type.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetImageDescription
Retrieves the image description of an encoded frame.
OSStatus ICMEncodedFrameGetImageDescription ( ICMEncodedFrameRef frame, ImageDescriptionHandle *imageDescOut );
Parameters
- frame
A reference to an encoded frame object.
- imageDescOut
A pointer to a handle containing the encoded frame’s image description. The caller should not dispose of this handle.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This function returns the same image description handle as ICMCompressionSessionGetImageDescription
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetMediaSampleFlags
Retrieves the media sample flags for an encoded frame.
MediaSampleFlags ICMEncodedFrameGetMediaSampleFlags ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
The object’s media
sample flags. These flags are listed in the header file Movies.h
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetSimilarity
Retrieves the similarity value for an encoded frame.
Float32 ICMEncodedFrameGetSimilarity ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
The encoded frame’s similarity value. 1.0 means identical; 0.0 means not at all alike. The default value is –1.0, which means unknown.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetSourceFrameRefCon
Retrieves the reference value of an encoded frame’s source frame.
void *ICMEncodedFrameGetSourceFrameRefCon ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Discussion
The source frame’s reference value is copied from the session’s sourceFrameRefCon parameter
that was passed to ICMCompressionSessionEncodeFrame
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetTimeScale
Retrieves the timescale of an encoded frame.
TimeScale ICMEncodedFrameGetTimeScale ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
The time scale of an encoded frame. This is always the same as the time scale of the compression session.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetTypeID
Returns the type ID for the current encoded frame object.
CFTypeID ICMEncodedFrameGetTypeID ( void );
Return Value
A CFTypeID
value.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameGetValidTimeFlags
Retrieves an encoded frame’s flags indicating which of its time stamps and durations are valid.
ICMValidTimeFlags ICMEncodedFrameGetValidTimeFlags ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object.
Return Value
One of the constants listed below.
Discussion
This function returns one of these values:
kICMValidTime_DisplayTimeStampIsValid = 1L<<0
The value of displayTimeStamp is valid.
kICMValidTime_DisplayDurationIsValid = 1L<<1
The value of displayDuration is valid.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameRelease
Decrements the retain count of an encoded frame object.
void ICMEncodedFrameRelease ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object. If you pass
NULL
, nothing happens.
Discussion
If the retain count drops to 0, the object is disposed.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameRetain
Increments the retain count of an encoded frame object.
ICMEncodedFrameRef ICMEncodedFrameRetain ( ICMEncodedFrameRef frame );
Parameters
- frame
A reference to an encoded frame object. If you pass
NULL
, nothing happens.
Return Value
A reference to the object passed in frame, for convenience.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameSetDataSize
Sets the data size of the compressed frame in an encoded frame’s buffer.
OSStatus ICMEncodedFrameSetDataSize ( ICMMutableEncodedFrameRef frame, ByteCount dataSize );
Parameters
- frame
A reference to an encoded frame object with write capabilities.
- dataSize
The data size of the compressed frame in the encoded frame object’s buffer.
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
ICMEncodedFrameSetDecodeDuration
Sets an encoded frame’s decode duration.
OSStatus ICMEncodedFrameSetDecodeDuration ( ICMMutableEncodedFrameRef frame, TimeValue64 decodeDuration );
Parameters
- frame
A reference to an encoded frame object with write capabilities.
- decodeDuration
The encoded frame’s decode duration.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This function automatically sets the kICMValidTime_DecodeDurationIsValid
flag.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameSetDecodeTimeStamp
Sets an encoded frame’s decode time stamp.
OSStatus ICMEncodedFrameSetDecodeTimeStamp ( ICMMutableEncodedFrameRef frame, TimeValue64 decodeTimeStamp );
Parameters
- frame
A reference to an encoded frame object with write capabilities.
- decodeTimeStamp
The encoded frame’s decode time stamp.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This function automatically sets the kICMValidTime_DecodeTimeStampIsValid
flag.
If the display time stamp is valid, it also sets the kICMValidTime_DisplayOffsetIsValid
flag.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameSetDisplayDuration
Sets an encoded frame’s display duration.
OSStatus ICMEncodedFrameSetDisplayDuration ( ICMMutableEncodedFrameRef frame, TimeValue64 displayDuration );
Parameters
- frame
A reference to an encoded frame object with write capabilities.
- displayDuration
The encoded frame’s display duration.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This function automatically sets the kICMValidTime_DisplayDurationIsValid
flag.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameSetDisplayTimeStamp
Sets an encoded frame’s display time stamp.
OSStatus ICMEncodedFrameSetDisplayTimeStamp ( ICMMutableEncodedFrameRef frame, TimeValue64 displayTimeStamp );
Parameters
- frame
A reference to an encoded frame object with write capabilities.
- displayTimeStamp
The encoded frame’s display time stamp.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This function automatically sets the kICMValidTime_DisplayTimeStampIsValid
flag.
If the decode time stamp is valid, it also sets the kICMValidTime_DisplayOffsetIsValid
flag.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameSetValidTimeFlags
Sets an encoded frame’s flags that indicate which of its time stamps and durations are valid.
OSStatus ICMEncodedFrameSetValidTimeFlags ( ICMMutableEncodedFrameRef frame, ICMValidTimeFlags validTimeFlags );
Parameters
- frame
A reference to an encoded frame object with write capabilities.
- validTimeFlags
One of the following constants:
kICMValidTime_DisplayTimeStampIsValid = 1L<<0
The value of displayTimeStamp is valid.
kICMValidTime_DisplayDurationIsValid = 1L<<1
The value of displayDuration is valid.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
Setting an encoded frame’s decode or display time stamp
or duration automatically sets the corresponding valid time flags.
For example, calling ICMEncodedFrameSetDecodeTimeStamp
sets kICMValidTime_DisplayTimeStampIsValid
.
If both the encoded frame’s decode time stamp and display time
stamp are valid, kICMValidTime_DisplayOffsetIsValid
is
automatically set.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMEncodedFrameSetMediaSampleFlags
Sets the media sample flags for an encoded frame.
OSStatus ICMEncodedFrameSetMediaSampleFlags ( ICMMutableEncodedFrameRef frame, MediaSampleFlags mediaSampleFlags );
Parameters
- frame
A reference to an encoded frame object with write capabilities.
- mediaSampleFlags
The object’s media sample flags. These flags are listed in the header file
Movies.h
.
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
ICMEncodedFrameSetFrameType
Sets the frame
type
for an encoded frame.
OSStatus ICMEncodedFrameSetFrameType ( ICMMutableEncodedFrameRef frame, ICMFrameType frameType );
Parameters
- frame
A reference to an encoded frame object with write capabilities.
- frameType
The frame type to be set:
kICMFrameType_I = 'I'
An I frame.
kICMFrameType_P = 'P'
A P frame.
kICMFrameType_B = 'B'
A B frame.
kICMFrameType_Unknown = 0
A frame of unknown type.
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
ICMEncodedFrameSetSimilarity
Sets the similarity for an encoded frame.
OSStatus ICMEncodedFrameSetSimilarity ( ICMMutableEncodedFrameRef frame, Float32 similarity );
Parameters
- frame
A reference to an encoded frame object with write capabilities.
- similarity
The encoded frame’s similarity value to be set. 1.0 means identical; 0.0 means not at all alike. The default value is –1.0, which means unknown.
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
ICMImageDescriptionGetProperty
Returns a particular property of a image description handle.
OSStatus ICMImageDescriptionGetProperty ( ImageDescriptionHandle inDesc, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ComponentValuePtr outPropValueAddress, ByteCount *outPropValueSizeUsed );
Parameters
- inDesc
The image description handle being interrogated.
- inPropClass
The class of property being requested.
- inPropID
The ID of the property being requested.
- inPropValueSize
The size of the property value buffer.
- outPropValueAddress
Points to the buffer to receive the property value.
- outPropValueSizeUsed
Points to a variable to receive the actual size of returned property value. (This can be
NULL
).
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This routine returns a particular property of a image description handle.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMImageDescriptionGetPropertyInfo
Returns information about a particular property of a image description.
OSStatus ICMImageDescriptionGetPropertyInfo ( ImageDescriptionHandle inDesc, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ComponentValueType *outPropType, /*can be NULL */ ByteCount *outPropValueSize, /*can be NULL */ UInt32 *outPropertyFlags );
Parameters
- inDesc
The image description handle being interrogated.
- inPropClass
The class of property being requested.
- inPropID
The ID of the property being requested.
- outPropType
The type of property is returned here. (This can be
NULL
).- outPropValueSize
The size of property is returned here. (This can be
NULL
).- outPropertyFlags
The property flags are returned here. (This can be
NULL
).
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
ICMImageDescriptionSetProperty
Sets a particular property of a image description handle.
OSStatus ICMImageDescriptionSetProperty ( ImageDescriptionHandle inDesc, ComponentPropertyClass inPropClass, ComponentPropertyID inPropID, ByteCount inPropValueSize, ConstComponentValuePtr inPropValueAddress );
Parameters
- inDesc
The image description handle being modified.
- inPropClass
The class of property being set.
- inPropID
The ID of the property being set.
- inPropValueSize
The size of property value.
- inPropValueAddress
Points to the property value buffer.
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
ICMMultiPassStorageCopyDataAtTimeStamp
Called by a multipass-capable compressor to retrieve data at a given time stamp.
OSStatus ICMMultiPassStorageCopyDataAtTimeStamp ( ICMMultiPassStorageRef multiPassStorage, TimeValue64 timeStamp, long index, CFMutableDataRef *dataOut );
Parameters
- multiPassStorage
The multipass storage object.
- timeStamp
The time stamp at which the value should be retrieved.
- index
An index by which multiple values may be stored at a time stamp. The meaning of individual indexes is private to the compressor.
- dataOut
A pointer to memory to receive the data at the time stamp.
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
ICMMultiPassStorageCreateWithCallbacks
Assembles a multipass storage mechanism from callbacks.
OSStatus ICMMultiPassStorageCreateWithCallbacks ( CFAllocatorRef allocator, ICMMultiPassStorageCallbacks *callbacks, ICMMultiPassStorageRef *multiPassStorageOut );
Parameters
- allocator
An allocator for this task. Pass
NULL
to use the default allocator.- callbacks
A structure containing a collection of callbacks for creating a custom multipass storage object. See
ICMMultiPassStorageCallbacks
.- multiPassStorageOut
A reference to the new multipass storage object.
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
ICMMultiPassStorageCreateWithTemporaryFile
Creates multipass storage using a temporary file.
OSStatus ICMMultiPassStorageCreateWithTemporaryFile ( CFAllocatorRef allocator, FSRef *directoryRef, CFStringRef fileName, ICMMultiPassStorageCreationFlags flags, ICMMultiPassStorageRef *multiPassStorageOut );
Parameters
- allocator
An allocator for this task. Pass
NULL
to use the default allocator.- directoryRef
A reference to a file directory. If you pass
NULL
, the ICM will use the user’s Temporary Items folder.- fileName
A file name to use for the storage. If you pass
NULL
, the ICM will pick a unique name. If you pass the name of a file that already exists, the ICM will assume you are continuing a previous multipass session where you left off. This file will be deleted when the multipass storage is released, unless you set thekICMMultiPassStorage_DoNotDeleteWhenDone
flag.- flags
Flag controlling this process:
kICMMultiPassStorage_DoNotDeleteWhenDone = 1L<<0
The temporary file should not be deleted when the multipass storage is released.
- multiPassStorageOut
A reference to the new multipass storage.
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
ICMMultiPassStorageGetTimeStamp
Called by a multipass-capable compressor to retrieve a time stamp for which a value is stored.
OSStatus ICMMultiPassStorageGetTimeStamp ( ICMMultiPassStorageRef multiPassStorage, TimeValue64 fromTimeStamp, ICMMultiPassStorageStep step, TimeValue64 *timeStampOut );
Parameters
- multiPassStorage
The multipass storage object.
- fromTimeStamp
The initial time stamp. This value is ignored for some values of step.
- step
Indicates the kind of time stamp search to perform:
kICMMultiPassStorage_GetFirstTimeStamp = 1
Requests the first time stamp at which a value is stored.
kICMMultiPassStorage_GetPreviousTimeStamp = 2
Requests the previous time stamp before the time stamp specified in fromTimeStamp at which a value is stored.
kICMMultiPassStorage_GetNextTimeStamp = 3
Requests the next time stamp after the time stamp specified in fromTimeStamp at which a value is stored.
kICMMultiPassStorage_GetLastTimeStamp = 4
Requests the last time stamp at which a value is stored.
- timeStampOut
A pointer to a
TimeValue64
value to receive the found time stamp. It will be set to –1 if no time stamp is found.
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
ICMMultiPassStorageGetTypeID
Returns the type ID for the current multipass storage object.
CFTypeID ICMMultiPassStorageGetTypeID ( void );
Return Value
A CFTypeID
value.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMMultiPassStorageRelease
Decrements the retain count of a multipass storage object.
void ICMMultiPassStorageRelease ( ICMMultiPassStorageRef multiPassStorage );
Parameters
- multiPassStorageOut
A reference to a multipass storage object. You can create this object using
ICMMultiPassStorageCreateWithTemporaryFile
orICMMultiPassStorageCreateWithCallbacks
. If you passNULL
, nothing happens.
Discussion
If the retain count drops to 0, the object is disposed.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMMultiPassStorageRetain
Increments the retain count of a multipass storage object.
ICMMultiPassStorageRef ICMMultiPassStorageRetain ( ICMMultiPassStorageRef multiPassStorage );
Parameters
- multiPassStorageOut
A reference to a multipass storage object. You can create this object using
ICMMultiPassStorageCreateWithTemporaryFile
orICMMultiPassStorageCreateWithCallbacks
. If you passNULL
, nothing happens.
Return Value
A reference to the object passed in multiPassStorage, for convenience.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ICMMultiPassStorageSetDataAtTimeStamp
Called by a multipass-capable compressor to store data at a given time stamp.
OSStatus ICMMultiPassStorageSetDataAtTimeStamp ( ICMMultiPassStorageRef multiPassStorage, TimeValue64 timeStamp, long index, CFDataRef data );
Parameters
- multiPassStorage
The multipass storage object.
- timeStamp
The time stamp at which the value should be stored.
- index
An index by which multiple values may be stored at a time stamp. The meaning of individual indexes is private to the compressor.
- data
The data to be stored, or
NULL
to delete the value.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
The new data replaces any previous data held at that time
stamp. If the value of data is NULL
,
the data for that time stamp is deleted. The format of the data
is private to the compressor.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
ImageCodecBeginPass
Notifies the compressor that it should operate in multipass mode and use the given multipass storage.
ComponentResult ImageCodecBeginPass ( ComponentInstance ci, ICMCompressionPassModeFlags passModeFlags, UInt32 flags, ICMMultiPassStorageRef multiPassStorage);
Parameters
- ci
A component instance that identifies a connection to an image codec component.
- passModeFlags
Indicates how the compressor should operate in this pass. If the
kICMCompressionPassMode_WriteToMultiPassStorage
flag is set, the compressor may gather information of interest and store it inmultiPassStorage
. If thekICMCompressionPassMode_ReadFromMultiPassStorage
flag is set, the compressor may retrieve information frommultiPassStorage
. If thekICMCompressionPassMode_OutputEncodedFrames flag
is set, the compressor must encode or drop every frame by callingICMCompressorSessionDropFrame
orICMCompressorSessionEmitEncodedFrame
. If that flag is not set, the compressor should not call these routines.- flags
Reserved. Ignore this parameter.
- multiPassStorage
The multipass storage object that the compressor should use to store and retrieve information between passes.
Return Value
An error code, or noErr
if
there is no error.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
ImageCodec.h
ImageCodecCompleteFrame
Directs the compressor to finish with a queued source frame, either emitting or dropping it.
ComponentResult ImageCodecCompleteFrame ( ComponentInstance ci, ICMCompressorSourceFrameRef sourceFrame, UInt32 flags );
Parameters
- ci
A component instance that identifies a connection to an image codec component.
- sourceFrame
The source frame that must be completed.
- flags
Reserved; ignore.
Return Value
An error code, or noErr
if
there is no error.
Discussion
This frame does not necessarily need to be the first or only
source frame emitted or dropped during this call, but the compressor
must call either ICMCompressorSessionDropFrame
or ICMCompressorSessionEmitEncodedFrame
with
this frame before returning. The ICM will call this function to
force frames to be encoded for the following reasons: (a) the maximum
frame delay count or maximum frame delay time in the compressionSessionOptions
does
not permit frames to be queued; (b) the client has called ICMCompressionSessionCompleteFrames
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Not supported
C interface file:
ImageCodec.h
ImageCodecDecodeBand
Returns an ImageSubCodecDecompressRecord
structure
for an image codec component.
ComponentResult ImageCodecDecodeBand ( ComponentInstance ci, ImageSubCodecDecompressRecord *drp, unsigned long flags );
Parameters
- ci
A component instance that identifies a connection to an image codec component.
- drp
A pointer to an
ImageSubCodecDecompressRecord
structure.- flags
Not used; set to 0.
Return Value
An error code, or noErr
if
there is no error.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Not supported
C interface file:
ImageCodec.h
ImageCodecEncodeFrame
Presents the compressor with a frame to encode.
ComponentResult ImageCodecEncodeFrame ( ComponentInstance ci, ICMCompressorSourceFrameRef sourceFrame, unsigned long flags );
Parameters
- ci
A component instance that identifies a connection to an image codec component.
- sourceFrame
The source frame to encode.
- flags
Reserved; ignore.
Return Value
An error code, or noErr
if
there is no error.
Discussion
The compressor may encode the frame immediately or queue it
for later encoding. If the compressor queues the frame for later
decode, it must retain it (by calling ICMCompressorSourceFrameRetain
)
and release it when it is done with it (by calling ICMCompressorSourceFrameRelease
).
Pixel buffers are guaranteed to conform to the pixel buffer attributes
returned by ImageCodecPrepareToCompressFrames
.
During multipass encoding, if the compressor requested the kICMCompressionPassMode_NoSourceFrames
flag, the
source frame pixel buffers may be NULL
.
(Note: this replaces ImageCodecBandCompress
.)
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Not supported
C interface file:
ImageCodec.h
ImageCodecPrepareToCompressFrames
Prepares the compressor to receive frames.
ComponentResult ImageCodecPrepareToCompressFrames ( ComponentInstance ci, ICMCompressorSessionRef session, ICMCompressionSessionOptionsRef compressionSessionOptions, ImageDescriptionHandle imageDescription, void *reserved, CFDictionaryRef *compressorPixelBufferAttributesOut);
Parameters
- ci
A component instance that identifies a connection to an image codec component.
- session
The compressor session reference. The compressor should store this in its globals; it will need it when calling the ICM back (for example, to call
ICMEncodedFrameCreateMutable
andICMCompressorSessionEmitEncodedFrame
). This is not a CF type. Do not callCFRetain
orCFRelease
on it.- compressionSessionOptions
The session options from the client. The compressor should retain this and use the settings to guide compression.
- imageDescription
The image description. The compressor may add image description extensions.
- reserved
Reserved for future use. Ignore this parameter.
- compressorPixelBufferAttributesOut
The compressor should create a pixel buffer attributes dictionary and set
compressorPixelBufferAttributesOut
to it. The ICM will release it.
Return Value
An error code, or noErr
if
there is no error.
Discussion
The compressor should record session and retain compressionSessionOptions
for
use in later calls. The compressor may modify imageDescription
at
this point. The compressor should create and return pixel buffer
attributes, which the ICM will release. (Note: this replaces ImageCodecPreCompress
.)
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Not supported
C interface file:
ImageCodec.h
ImageCodecProcessBetweenPasses
Provides the compressor with an opportunity to perform processing between passes.
ComponentResult ImageCodecProcessBetweenPasses ( ComponentInstance ci, ICMMultiPassStorageRef multiPassStorage, Boolean *interpassProcessingDoneOut, ICMCompressionPassModeFlags *requestedNextPassModeFlagsOut );
Parameters
- ci
A component instance that identifies a connection to an image codec component.
- multiPassStorage
The multipass storage object that the compressor should use to store and retrieve information between passes.
- interpassProcessingDoneOut
Points to a Boolean. Set this to
FALSE
if you want yourImageCodecProcessBetweenPasses
function to be called again to perform more processing,TRUE
if not.- requestedNextPassModeFlagsOut
Set
*requestedNextPassModeFlagsOut
to indicate the type of pass that should be performed next: To recommend a repeated analysis pass, set it tokICMCompressionPassMode_ReadFromMultiPassStorage| kICMCompressionPassMode_WriteToMultiPassStorage
. To recommend a final encoding pass, set it tokICMCompressionPassMode_ReadFromMultiPassStorage | kICMCompressionPassMode_OutputEncodedFrames
. If source frame buffers are not necessary for the recommended pass (for example, because all the required data has been copied into multipass storage), setkICMCompressionPassMode_NoSourceFrames
.
Return Value
An error code, or noErr
if
there is no error.
Discussion
This function will be called repeatedly until it returns TRUE
in
*interpassProcessingDoneOut
.
The compressor may read and write to multiPassStorage
.
The compressor should indicate which type of pass it would prefer
to perform next by setting *requestedNextPassTypeOut
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Not supported.
C interface file:
ImageCodec.h
InvokeQTTrackPropertyListenerUPP
Invokes the specified property listener of a track.
void InvokeQTTrackPropertyListenerUPP ( Track inTrack, QTPropertyClass inPropClass, QTPropertyID inPropID, void *inUserData, QTTrackPropertyListenerUPP userUPP );
Parameters
- inTrack
The track of this operation.
- inPropClass
A property class.
- inPropID
A property ID.
- inUserData
A pointer to user data that will be passed to the callback.
- userUPP
A
QTTrackPropertyListenerUPP
pointer.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
Movies.h
MediaContainsDisplayOffsets
Tests whether a media contains display offsets.
Boolean MediaContainsDisplayOffsets ( Media theMedia );
Parameters
- theMedia
The media for this operation. You obtain this media identifier from such functions as
NewTrackMedia
andGetTrackMedia
.
Return Value
TRUE
if
the media is valid and contains at least one sample with a nonzero display
offset; FALSE
otherwise.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
MediaDecodeTimeToSampleNum
Finds the sample for a specified decode time.
void MediaDecodeTimeToSampleNum ( Media theMedia, TimeValue64 decodeTime, SInt64 *sampleNum, TimeValue64 *sampleDecodeTime, TimeValue64 *sampleDecodeDuration );
Parameters
- theMedia
The media for this operation. You obtain this media identifier from such functions as
NewTrackMedia
andGetTrackMedia
.- decodeTime
A 64-bit time value that represents the decode time for which you are retrieving sample information. You must specify this value in the media's time scale.
- sampleNum
A pointer to a variable that is to receive the sample number. The function returns the sample number that identifies the sample that contains data for the specified decode time, or 0 if it is not found.
- sampleDecodeTime
A pointer to a time value. The function updates this time value to indicate the decode time of the sample specified by the logicalSampleNum parameter. This time value is expressed in the media’s time scale. Set this parameter to
NULL
if you do not want this information.- sampleDecodeDuration
A pointer to a time value. The function updates this time value to indicate the decode duration of the sample specified by the logicalSampleNum parameter. This time value is expressed in the media’s time scale. Set this parameter to
NULL
if you do not want this information.
Discussion
You can access this function's error returns through GetMoviesError
and GetMoviesStickyError
.
It returns paramErr
if there is a bad
parameter value, invalidTime
if sampleDecodeTime is
out of the decode time range, or noErr
if
there is no error.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
MediaDisplayTimeToSampleNum
Fnds the sample number for a specified display time.
void MediaDisplayTimeToSampleNum ( Media theMedia, TimeValue64 displayTime, SInt64 *sampleNum, TimeValue64 *sampleDisplayTime, TimeValue64 *sampleDisplayDuration );
Parameters
- theMedia
The media for this operation. You obtain this media identifier from such functions as
NewTrackMedia
andGetTrackMedia
.- displayTime
A 64-bit time value that represents the display time for which you are retrieving sample information. You must specify this value in the media’s time scale.
- sampleNum
A pointer to a long integer that is to receive the sample number. The function returns the sample number that identifies the sample for the specified display time, or 0 if it is not found.
- sampleDisplayTime
A pointer to a time value. The function updates this time value to indicate the display time of the sample specified by the logicalSampleNum parameter. This time value is expressed in the media’s time scale. Set this parameter to
NULL
if you do not want this information.- sampleDisplayDuration
A pointer to a time value. The function updates this time value to indicate the display duration of the sample specified by the logicalSampleNum parameter. This time value is expressed in the media’s time scale. Set this parameter to
NULL
if you do not want this information.
Discussion
You can access this function's error returns through GetMoviesError
and GetMoviesStickyError
.
It returns paramErr
if there is a bad
parameter value, invalidTime if sampleDisplayTime is
out of the display time range, or noErr
if
there is no error.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
MovieAudioExtractionBegin
Begins a movie audio extraction session and will return badCallOrderErr
if
the specified movie is not Active.
OSStatus MovieAudioExtractionBegin ( Movie m, UInt32 flags, MovieAudioExtractionRef *outSession );
Parameters
- m
The movie for this operation. Your application obtains this movie identifier from such functions as
NewMovie
,NewMovieFromProperties
,NewMovieFromFile
, andNewMovieFromHandle
.- flags
Reserved; must be 0.
- outSession
A pointer to an opaque session object.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
You must call this function before doing any movie audio extraction,
because you will pass the object returned by outSession to
the other movie audio extraction functions. The format of the extracted
audio defaults to the summary channel layout of the movie (all right
channels mixed together, all left surround channels mixed together,
and so on.), 32-bit float, de-interleaved, with the sample rate
set to the highest sample rate found in the movie. You can set the
audio format to be something else, as long as it is uncompressed and
you do it before your first call to MovieAudioExtractionFillBuffer
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
MovieAudioExtractionEnd
Ends a movie audio extraction session.
OSStatus MovieAudioExtractionEnd ( MovieAudioExtractionRef session );
Parameters
- session
The session object returned by
MovieAudioExtractionBegin
.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
You must call this function when movie audio extraction is complete.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
MovieAudioExtractionFillBuffer
Extracts audio from a movie.
OSStatus MovieAudioExtractionFillBuffer ( MovieAudioExtractionRef session, UInt32 *ioNumFrames, AudioBufferList *ioData, UInt32 *outFlags );
Parameters
- session
The session object returned by
MovieAudioExtractionBegin
.- ioNumFrames
A pointer to the number of PCM frames to be extracted.
- ioData
A pointer to an AudioBufferList allocated by the caller to hold the extracted audio data.
- outFlags
A bit flag that indicates when extraction is complete:
kMovieAudioExtractionComplete
The extraction process is complete. Value is
(1L << 0)
.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
You call this function repeatedly; each call continues extracting
audio where the last call left off. The function will extract as
many of the requested PCM frames as it can, given the limits of
the buffer supplied and the limits of the input movie. ioNumFrames will
be updated with the exact number of valid frames being returned.
When there is no more audio to extract from the movie, the function
will continue to return noErr
but
will return no further audio data. In this case, the outFlags parameter
will have its kMovieAudioExtractionComplete
bit
set. It is possible that the kMovieAudioExtractionComplete
bit
will accompany the last buffer of valid data.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
MovieAudioExtractionGetProperty
Gets a property of a movie audio extrraction session.
OSStatus MovieAudioExtractionGetProperty ( MovieAudioExtractionRef session, QTPropertyClass inPropClass, QTPropertyID inPropID, ByteCount inPropValueSize, QTPropertyValuePtr outPropValueAddress, ByteCount *outPropValueSizeUsed);
Parameters
- session
The session object returned by
MovieAudioExtractionBegin
.- inPropClass
Pass the following constant to define the property class: Property of an audio presentation; value is
'audi'
.- inPropID
The property ID.
- inPropValueSize
The size of the buffer allocated to receive the property value.
- outPropValueAddress
A pointer to the buffer allocated to receive the property value.
- outPropValueSizeUsed
The actual size of the property value.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
You can get and set more than just the channel layout. There
are four properties, discussed below, all of which are gettable
and settable (with some having restrictions on not setting after
first calling MovieAudioExtractionFillBuffer
).
Properties of the movie that is extracted from kQTPropertyClass_MovieAudioExtraction_Movie
include
the following movie class IDs:
kQTMovieAudioExtractionMoviePropertyID_CurrentTime
. The value is aTimeRecord
, which you can set and get. When setting, you set the timescale to anything you want (for example, the output audio sample rate or the movie timescale). When getting, the timescale will be output audio sample rate for best accuracy.kQTMovieAudioExtractionMoviePropertyID_AllChannelsDiscrete
. The value is Boolean (which is settable and gettable). Set to implement export of all audio channels without mixing. When this is set and the extraction audio stream basic description (ASBD) or channel layout are read back, you get information relating to the re-mapped movie.kQTMovieAudioExtractionMoviePropertyID_CurrentTime = ‘time’
. The value is aTimeRecord
, which is gettable and settable.
Properties of the output audio extracted from kQTPropertyClass_MovieAudioExtraction_Audio
include
the following output audio class properties:
kQTMovieAudioExtractionAudioPropertyID_AudioStreamBasicDescription
. The value is anAudioStreamBasicDescription
. You can get any time and set before first theMovieAudioExtractionFillBuffer
call. If you get this property immediately after beginning an audio extraction session, it will tell you the default extraction format for the movie. This will include the number of channels in the default movie mix. If you set the outputAudioStreamBasicDescription
, it is recommended that you also set the output channel layout. If your output ASBD has a different number of channels than the default extraction mix, you must set the output channel layout. You can only set PCM output formats. Setting a compressed output format will fail.:
kQTMovieAudioExtractionAudioPropertyID_AudioChannelLayout
. The value isAudioChannelLayout
, which you can get any time and set before first theMovieAudioExtractionFillBuffer
call. If you get this property immediately after beginning an audio extraction session, it tells you what the channel layout is for the default extraction mix.
The information in this discussion also applies to the following functions:
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
MovieAudioExtractionGetPropertyInfo
Gets information about a property of a movie audio extraction session.
OSStatus MovieAudioExtractionGetPropertyInfo ( MovieAudioExtractionRef session, QTPropertyClass inPropClass, QTPropertyID inPropID, QTPropertyValueType *outPropType, ByteCount *outPropValueSize, UInt32 *outPropertyFlags );
Parameters
- session
The session object returned by
MovieAudioExtractionBegin
.- inPropClass
Pass the following constant to define the property class: Property of an audio presentation; value is
'audi
- inPropID
The property ID.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueSize
A pointer to the size of the returned property’s value.
- outPropFlags
On return, a pointer to flags representing the requested information about the item’s property.
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
MovieAudioExtractionSetProperty
Sets a property of a movie audio extraction session.
OSStatus MovieAudioExtractionSetProperty ( MovieAudioExtractionRef session, QTPropertyClass inPropClass, QTPropertyID inPropID, ByteCount inPropValueSize, ConstQTPropertyValuePtr inPropValueAddress );
Parameters
- session
The session object returned by
MovieAudioExtractionBegin
.- inPropClass
Pass the following constant to define the property class: Property of an audio presentation; value is
'audi'
.- inPropID
Pass one of these constants to define the property ID:
kQTAudioPropertyID_SummaryChannelLayout
The summary audio channel layout of a movie, or any other grouping of audio streams. All like-labeled channels are combined, without duplicates. For example, if there is a stereo (L/R) track, 5 single-channel tracks marked Left, Right, Left Surround, Right Surround and Center, and a 4-channel track marked L/R/Ls/Rs, then the summary AudioChannelLayout will be L/R/Ls/Rs/C, not L/R/L/R/Ls/Rs/C/L/R/Ls/Rs. The value of this constant is
'clay'
.
- inPropValueSize
The size of the property value.
- inPropValueAddress
A const void pointer that points to the property value.
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
NewMovieExportStageReachedCallbackUPP
Allocates a new Universal Procedure Pointer for a MovieExportStageReachedCallbackProc
callback.
MovieExportStageReachedCallbackUPP NewMovieExportStageReachedCallbackUPP ( MovieExportStageReachedCallbackProcPtr userRoutine );
Parameters
- userRoutine
A pointer to your application-defined callback function; see
ICMDecompressionTrackingCallbackProc
.
Return Value
A new Universal Procedure Pointer that you will use to invoke your callback.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
QuickTimeComponents.h
NewMovieFromProperties
Creates a new movie using movie properties.
OSStatus NewMovieFromProperties ( ItemCount inputPropertyCount, QTNewMoviePropertyElement *inputProperties, ItemCount outputPropertyCount, QTNewMoviePropertyElement *outputProperties, Movie *theMovie );
Parameters
- inputPropertyCount
The number of properties in the array passed in inputProperties.
- inputProperties
A pointer to a property array describing how to instantiate the movie. See
QTNewMoviePropertyElement
.- outputPropertyCount
The number of properties in the array passed in outputProperties.
- outputProperties
A pointer to a property array to receive output parameters. See
QTNewMoviePropertyElement
. You may passNULL
if you don’t want this information. The caller is responsible for calling the appropriate routines to dispose of any property values returned here. Since callers specify the property classes and IDs, they know who to call to dispose of the property values.- theMovie
A pointer to a variable that receives the new movie.
Return Value
An error code. Returns memFullErr
if
the function could not allocate memory, paramErr
if inputProperties or theMovie is NULL
,
or noErr
if there is no error.
Discussion
This function can be used in all the cases where an existing NewMovieFrom...
call
is used. When calling this function, you supply a set of input properties
that describe the information required to instantiate the movie
(its data reference, audio context, visual context, and so on).
You can also supply a set of output properties that you may be interested
in; for example, information about whether the data reference was
changed. See New Movie Property Codes.
This function verifies its input properties is as follows.
First, the propStatus
field of both the input
and output property arrays is set to kQTPropertyUnprocessedErr
.
Then the input properties are checked one by one. If there is no
problem with a property, its propStatus
is
set to noErr
(0). If there is a problem,
the propStatus
for the property is set to 1
and the function returns paramErr
.
It is an error if a property is not recognized; paramErr
is returned
and the appropriate propStatus
is set to kQTPropertyNotSupportedErr
.
Another error is multiple data locations defined. In this case,
the property status for the second data location is set to paramErr
.
It is not considered a fatal error if this function does not recognize
an output property; the property’s propStatus
simply
remains kQTPropertyUnprocessedErr
.
The only output properties currently defined are those that
support the behavior of functions of the form NewMovieFrom...
.
For example, if you want to act upon the data reference being updated
during the opening process, you would pass in the kQTMovieInstantiationPropertyID_ResultDataLocationChanged
property.
This function must be used with kQTContextPropertyID_VisualContext
to
open a movie, for visual contexts to function with the movie. If
you want to use visual contexts with a movie but want to inspect
the movie prior to allocating the visual context to use (for instance
you want to get the movie box), use kQTContextPropertyID_VisualContext
with a NULL
value.
Otherwise, visual context calls with the movie will fail with an
error. Using GWorld
structures with the movie
will also fail.
To handle special situations where this function cannot be
used by your application, there is a method to switch a movie from
GWorld mode to visual context mode. SetMovieVisualContext
can
be used to set a NULL
visual
context, which will disassociate the movie from its current visual
context or GWorld. At this time, either SetMovieGWorld
or SetMovieVisualContext
can
be used. If a movie is associated with a GWorld, visual context
calls such as GetMovieVisualContext
will
fail. If a movie is a associated with a valid visual context, GWorld
calls such as GetMovieGWorld
will fail.
If a call to this function succeeds using a visual context or audio context, those objects will be explicitly retained for use by the movie. The movie object is responsible for releasing them. If you no longer need access to a context, it is safe to release it.
If no data location property is specified, then this function
will behave like NewMovie
, creating
an empty movie. Thus NewMovieFromProperties(0,
nil, 0, nil, &movie)
is functionally equivalent
to movie = NewMovie(0)
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
NewQTTrackPropertyListenerUPP
Creates a new callback to monitor a track property.
QTTrackPropertyListenerUPP NewQTTrackPropertyListenerUPP ( QTTrackPropertyListenerProcPtr userRoutine );
Parameters
- userRoutine
A pointer to a QTTrackPropertyListenerProcPtr callback.
Return Value
A new UPP; see Universal
Procedure Pointers in the QuickTime API Reference
.
Discussion
This routine creates a new callback to monitor a track property.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTAddTrackPropertyListener
Installs a callback to monitor a track property.
OSErr QTAddTrackPropertyListener ( Track inTrack, QTPropertyClass inPropClass, QTPropertyID inPropID, QTTrackPropertyListenerUPP inListenerProc, void *inUserData );
Parameters
- inTrack
The track for this operation.
- inPropClass
A property class.
- inPropID
A property ID.
- inListenerProc
A Universal Procedure Pointer to a QTTrackPropertyListenerProc callback.
- inUserData
A pointer to user data that will be passed to the callback.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This routine installs a callback to monitor a track property.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTAudioContextCreateForAudioDevice
Creates a QTAudioContext object that encapsulates a connection to a CoreAudio output device.
OSStatus QTAudioContextCreateForAudioDevice ( CFAllocatorRef allocator, CFStringRef coreAudioDeviceUID, CFDictionaryRef options, QTAudioContextRef *newAudioContextOut );
Parameters
- allocator
Allocator used to create the audio context.
- coreAudioDeviceUID
CoreAudio device UID.
NULL
means the default device.- options
Reserved. Pass
NULL
.- newAudioContextOut
Points to a variable to receive the new audio context.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This routine creates a QTAudioContext object that encapsulates
a connection to a CoreAudio output device. This object is suitable
for passing to SetMovieAudioContext
or NewMovieFromProperties
,
which targets the audio output of the movie to that device. A QTAudioContext
object cannot be associated with more than one movie. Each movie needs
its own connection to the device. In order to play more than one
movie to a particular device, create a QTAudioContext object for
each movie. You are responsible for releasing the QTAudioContext
object created by this routine. After calling SetMovieAudioContext
or NewMovieFromProperties
,
you can release the object since these APIs will retain it for their
own use. On Windows, the audioDeviceUID
is
the GUID of a DirectSound device, stringified using such Win32 functions
as StringFromCLSID
or StringFromGUID2
,
then wrapped in a CFStringRef using CFStringCreateWithCharacters
. After
passing the audioDeviceUID
CFStringRef
to QTAudioContextCreateForAudioDevice
,
remember to CFRelease
the CFStringRef
you created.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTCopyMovieMetaData
Retains a movie’s metadata object and returns it.
OSStatus QTCopyMovieMetaData ( Movie inMovie, QTMetaDataRef *outMetaData );
Parameters
- inMovie
The movie for this operation. Your application obtains this movie identifier from such functions as
NewMovie
,NewMovieFromProperties
,NewMovieFromFile
, andNewMovieFromHandle
.- outMetaData
A pointer to an opaque metadata object wrapper associated with the movie passed in inMovie.
Return Value
Returns invalidMovie
if
the movie passed in inMovie is invalid,
or noErr
if there is no error.
Discussion
This function returns the metadata object associated with
a movie. The object has retain/release semantics. It has already
been retained before returning, but you should call QTMetaDataRelease
when
you are done. Because the movie can be disposed of at any time, the QTMetaDataRef
may
be valid when the movie no longer exists. In this case, the function will
fail with a kQTMetaDataInvalidMetaDataErr
error.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTCopyTrackMetaData
Retains a track’s metadata object and returns it.
OSStatus QTCopyTrackMetaData ( Track inTrack, QTMetaDataRef *outMetaData );
Parameters
- inTrack
A track identifier, which your application obtains from such functions as
NewMovieTrack
andGetMovieTrack
.- outMetaData
A pointer to an opaque metadata object wrapper associated with the track passed in inTrack.
Return Value
Returns invalidMedia
if
the track passed in inTrack is invalid,
or noErr
if there is no error.
Discussion
This function returns the metadata object associated with
a track. The object has retain/release semantics. It has already
been retained before returning, but you should call QTMetaDataRelease
when
you are done. Because the track can be disposed of at any time, the QTMetaDataRef
may
be valid when the track no longer exists. In this case, the function will
fail with a kQTMetaDataInvalidMetaDataErr
error.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTCopyMediaMetaData
Retains a media’s metadata object and returns it.
OSStatus QTCopyMediaMetaData ( Media inMedia, QTMetaDataRef *outMetaData );
Parameters
- inMedia
The media for this operation. You obtain this media identifier from such functions as
NewTrackMedia
andGetTrackMedia
.- outMetaData
A pointer to an opaque metadata object wrapper associated with the media passed in inMedia.
Return Value
Returns invalidMedia
if
the media passed in inMedia is invalid,
or noErr
if there is no error.
Discussion
This function returns the metadata object associated with
a media. The object has retain/release semantics. It has already
been retained before returning, but you should call QTMetaDataRelease
when
you are done. Because the media can be disposed of at any time, the QTMetaDataRef
may
be valid when the media no longer exists. In this case, the function will
fail with a kQTMetaDataInvalidMetaDataErr
error.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTGetTrackProperty
Returns the value of a specific track property.
OSErr QTGetTrackProperty ( Track inTrack, QTPropertyClass inPropClass, QTPropertyID inPropID, ByteCount inPropValueSize, QTPropertyValuePtr outPropValueAddress, ByteCount *outPropValueSizeUsed );
Parameters
- inTrack
The track for this operation.
- inPropClass
A property class.
- inPropID
A property ID.
- inPropValueSize
The size of the buffer allocated to hold the property value.
- outPropValueAddress
A pointer to the buffer allocated to hold the property value.
- outPropValueSizeUsed
On return, the actual size of the value written to the buffer.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This routine returns the value of a specific track property.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTGetTrackPropertyInfo
Returns information about the properties of a track.
OSErr QTGetTrackPropertyInfo ( Track inTrack, QTPropertyClass inPropClass, QTPropertyID inPropID, QTPropertyValueType *outPropType, ByteCount *outPropValueSize, UInt32 *outPropertyFlags );
Parameters
- inTrack
The track for this operation.
- inPropClass
A property class.
- inPropID
A property ID.
- outPropType
A pointer to memory allocated to hold the
property
type on return.- outPropValueSize
A pointer to memory allocated to hold the size of the property value on return.
- outPropertyFlags
A pointer to memory allocated to hold property flags on return.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This routine returns information about the properties of a track.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTLoadLibrary
Finds and loads a QuickTime library DLL.
HINSTANCE QTLoadLibrary ( const char *szDLL );
Parameters
- szDLL
The name, not the full path for this operation.
Return Value
If the function succeeds, the return value is the instance handle.
Discussion
This routine takes the name of the QuickTime DLL and searches all the places where it can be installed.
Version Notes
Introduced in QuickTime 7 for Windows.
Availability
- C interface file:
QTLoadLibraryUtils.h
QTMetaDataAddItem
Adds an inline metadata item to the metadata storage format.
OSStatus QTMetaDataAddItem ( QTMetaDataRef inMetaData, QTMetaDataStorageFormat inMetaDataFormat, QTMetaDataKeyFormat inKeyFormat, const UInt8 *inKeyPtr, ByteCount inKeySize, const UInt8 *inValuePtr, ByteCount inValueSize, UInt32 inDataType, QTMetaDataItem *outItem);
Parameters
- inMetaData
The metadata object for this operation.
- inMetaDataFormat
The metadata storage format used by the object passed in inMetaData. The format may be
UserData
storage, iTunes metadata storage, or QuickTime metadata storage. Not all objects will include all forms of storage, and other storage formats may appear in the future. You cannot passkQTMetaDataStorageFormatWildcard
to target all storage formats.- inKeyFormat
The format of the key.
- inKeyPtr
A pointer to the key of the item to be fetched next. You may pass
NULL
in this parameter if you are not interested in any specific key.- inKeySize
The size of the key in bytes.
- inValuePtr
A pointer to the value to be added. This can be
NULL
if inValueSize is 0.- inValueSize
The size of inValuePtr in bytes. Pass 0 if you want to add an item with no value.
- inDataType
A data type from the following list:
kQTMetaDataTypeBinary = 0,
kQTMetaDataTypeUTF8 = 1,
kQTMetaDataTypeUTF16BE = 2,
kQTMetaDataTypeMacEncodedText = 3,
kQTMetaDataTypeSignedIntegerBE = 21,
kQTMetaDataTypeUnsignedIntegerBE = 22,
kQTMetaDataTypeFloat32BE = 23,
kQTMetaDataTypeFloat64BE = 24
With
kQTMetaDataTypeSignedIntegerBE
andkQTMetaDataTypeUnsignedIntegerBE
, the size of the integer is determined by the value size.- outItem
On return, a pointer to an opaque, unique
UInt64
identifier of the newly added item. Your application can use this to identify the metadata item within a metadata object for other metadata functions. You may passNULL
if you are not interested in the identifier of the newly added item. This identifier does not need to be disposed of.
Return Value
Returns kQTMetaDataInvalidMetaDataErr
if
the metadata object or its reference is invalid, kQTMetaDataInvalidStorageFormatErr
if
the metatada storage format is invalid, kQTMetaDataInvalidKeyErr
if
the key or its format is invalid, or noErr
if
there is no error. See “Metadata Error Codes”
.
Discussion
The data type of the metadata item is assumed to be binary.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataGetItemCountWithKey
Returns the number of items in a metadata storage format with a certain key.
OSStatus QTMetaDataGetItemCountWithKey ( QTMetaDataRef inMetaData, QTMetaDataStorageFormat inMetaDataFormat, QTMetaDataKeyFormat inKeyFormat, const UInt8 *inKeyPtr, ByteCount inKeySize, ItemCount *outCount);
Parameters
- inMetaData
The metadata object for this operation.
- inMetaDataFormat
The metadata storage format used by the object passed in inMetaData. The format may be
UserData
storage, iTunes metadata storage, or QuickTime metadata storage. Not all objects will include all forms of storage, and other storage formats may appear in the future. You cannot passkQTMetaDataStorageFormatWildcard
to target all storage formats.- inKeyFormat
The format of the key.
- inKeyPtr
A pointer to the key of the item to be fetched next. You may pass
NULL
in this parameter if you are not interested in any specific key.- inKeySize
The size of the key in bytes.
- outCount
The number of items in the metadata storage format that have the specified key.
Return Value
Returns kQTMetaDataInvalidMetaDataErr
if
the metadata object or its reference is invalid, kQTMetaDataInvalidStorageFormatErr
if
the metatada storage format is invalid, kQTMetaDataInvalidKeyErr
if
the key or its format is invalid, or noErr
if
there is no error. See “Metadata Error Codes”
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataGetItemProperty
Returns a property of a metadata item.
OSStatus QTMetaDataGetItemProperty ( QTMetaDataRef inMetaData, QTMetaDataItem inItem, QTPropertyClass inPropClass, QTPropertyID inPropID, ByteCount inPropValueSize, QTPropertyValuePtr outPropValueAddress, ByteCount *outPropValueSizeUsed );
Parameters
- inMetaData
The metadata object for this operation.
- inItem
The opaque, unique
UInt64
identifier of the metadata item for this operation. Your application obtains this item identifier from such functions asQTMetaDataAddItem
andQTMetaDataGetNextItem
.- inPropClass
The class of the property being asked about.
- inPropID
The ID of the property being asked about.
- inPropValueSize
Size of the buffer allocated to receive the property value.
- outPropValueAddress
A pointer to the buffer allocated to receive the item’s property value.
- outPropValueSizeUsed
On return, the actual size of buffer space used.
Return Value
Returns kQTMetaDataInvalidMetaDataErr
if
the metadata object or its reference is invalid, kQTMetaDataInvalidItemErr
if
the metatada item ID is invalid, errPropNotSupported
if
the metatada object does not support the property being asked about, buffersTooSmall
if
the allocated buffer is too small to hold the property, or noErr
if
there is no error. See “Metadata Error Codes”
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataGetItemPropertyInfo
Returns information about a property of a metadata item.
OSStatus QTMetaDataGetItemPropertyInfo ( QTMetaDataRef inMetaData, QTMetaDataItem inItem, QTPropertyClass inPropClass, QTPropertyID inPropID, QTPropertyValueType *outPropType, ByteCount *outPropValueSize, UInt32 *outPropFlags );
Parameters
- inMetaData
The metadata object for this operation.
- inItem
The opaque, unique
UInt64
identifier of the metadata item for this operation. Your application obtains this item identifier from such functions asQTMetaDataAddItem
andQTMetaDataGetNextItem
.- inPropClass
The class of the property being asked about.
- inPropID
The ID of the property being asked about.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueSize
A pointer to the size of the returned property’s value.
- outPropFlags
On return, a pointer to flags representing the requested information about the item’s property.
Return Value
Returns kQTMetaDataInvalidMetaDataErr
if
the metadata object or its reference is invalid, kQTMetaDataInvalidItemErr
if
the metatada item ID is invalid, errPropNotSupported
if
the metatada object does not support the item property being asked
about, or noErr
if there is no error.
See “Metadata Error Codes”
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataGetItemValue
Returns the value of a metadata item from an item identifier.
OSStatus QTMetaDataGetItemValue ( QTMetaDataRef inMetaData, QTMetaDataItem inItem, UInt8 *outValuePtr, ByteCount inValueSize, ByteCount *outActualSize );
Parameters
- inMetaData
The metadata object for this operation.
- inItem
The opaque, unique
UInt64
identifier of the metadata item for this operation. Your application can obtain this item identifier from such functions asQTMetaDataAddItem
.- outValuePtr
A pointer to the first value of the item. You may pass
NULL
in this parameter if you just want to find out the size of the buffer needed.- inValueSize
The number of bytes in the outValuePtr buffer. You may pass 0 if you just want to find out the size of the buffer needed.
- outActualSize
The actual size of the value if this parameter is not
NULL
.
Return Value
Returns kQTMetaDataInvalidMetaDataErr
if
the metadata object or its reference is invalid, kQTMetaDataInvalidItemErr
if
the metatada item ID is invalid, or noErr
if
there is no error. See “Metadata Error Codes”
.
Discussion
You can use this function to get the value of a metadata item that has a known item identifier.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataGetNextItem
Returns the next metadata item corresponding to a specified key.
OSStatus QTMetaDataGetNextItem ( QTMetaDataRef inMetaData, QTMetaDataStorageFormat inMetaDataFormat, QTMetaDataItem inCurrentItem, QTMetaDataKeyFormat inKeyFormat, const UInt8 *inKeyPtr, ByteCount inKeySize, QTMetaDataItem *outNextItem );
Parameters
- inMetaData
The metadata object for this operation.
- inMetaDataFormat
The metadata storage format used by the object passed in inMetaData. The format may be
UserData
storage, iTunes metadata storage, or QuickTime metadata storage. Not all objects will include all forms of storage, and other storage formats may appear in the future. PasskQTMetaDataStorageFormatWildcard
to target all storage formats.- inCurrentItem
The opaque, unique
UInt64
identifier of the current metadata item to start the search. Your application obtains this item identifier from such functions asQTMetaDataAddItem
.- inKeyFormat
The format of the key.
- inKeyPtr
A pointer to the key of the item to be fetched next. You may pass
NULL
in this parameter if you are not interested in any specific key.- inKeySize
The size of the key in bytes.
- outNextItem
The ID of the next metadata item after the item specified by inCurrentItem that has the specified key.
Return Value
Returns kQTMetaDataInvalidMetaDataErr
if
the metadata object or its reference is invalid, kQTMetaDataInvalidItemErr
if
the metatada item ID is invalid, kQTMetaDataInvalidStorageFormatErr
if
the metatada storage format is invalid, kQTMetaDataInvalidKeyErr
if
the key or its format is invalid, kQTMetaDataNoMoreItemErr
if
the last item has been fetched, or noErr
if
there is no error. See “Metadata Error Codes”
.
Discussion
If the item designated by inCurrentItem is kQTMetaDataItemUninitialized
,
the function returns the first item with the specified key in the
storage format. If it refers to a valid item in the storage format,
the function will return the next item with the key after the item designated
by inCurrentItem.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataGetProperty
Returns a property of a metadata object.
OSStatus QTMetaDataGetProperty ( QTMetaDataRef inMetaData, QTPropertyClass inPropClass, QTPropertyID inPropID, ByteCount inPropValueSize, QTPropertyValuePtr outPropValueAddress, ByteCount *outPropValueSizeUsed );
Parameters
- inMetaData
The metadata object for this operation.
- inPropClass
The class of the property being asked about.
- inPropID
The ID of the property being asked about.
- inPropValueSize
Size of the buffer allocated to receive the property value.
- outPropValueAddress
A pointer to the buffer allocated to receive the property value.
- outPropValueSizeUsed
On return, the actual size of buffer space used.
Return Value
Returns kQTMetaDataInvalidMetaDataErr
if
the metadata object or its reference is invalid, errPropNotSupported
if
the metatada object does not support the property being asked about, buffersTooSmall
if
the allocated buffer is too small to hold the property, or noErr
if
there is no error. See “Metadata Error Codes”
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataGetPropertyInfo
Returns information about a property of a metadata object.
OSStatus QTMetaDataGetPropertyInfo ( QTMetaDataRef inMetaData, QTPropertyClass inPropClass, QTPropertyID inPropID, QTPropertyValueType *outPropType, ByteCount *outPropValueSize, UInt32 *outPropFlags );
Parameters
- inMetaData
The metadata object for this operation.
- inPropClass
The class of the property being asked about.
- inPropID
The ID of the property being asked about.
- outPropType
A pointer to the type of the returned property’s value.
- outPropValueSize
A pointer to the size of the returned property’s value.
- outPropFlags
On return, a pointer to flags representing the requested information about the property.
Return Value
Returns kQTMetaDataInvalidMetaDataErr
if
the metadata object or its reference is invalid, errPropNotSupported
if
the metatada object does not support the property being asked about,
or noErr
if there is no error. See “Metadata Error Codes”
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataRetain
Increments the retain count of a metadata object.
QTMetaDataRef QTMetaDataRetain ( QTMetaDataRef inMetaData );
Parameters
- inMetaData
A metadata object that you want to retain.
Return Value
If successful, returns a metadata object that is the same as that passed in inMetaData.
Discussion
This function retains a metadata object by incrementing its
reference count. You should retain every metadata object when you
receive it from elsewhere and you want it to persist. If you retain
a metadata object you are responsible for releasing it by calling QTMetaDataRelease
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataRelease
Decrements the retain count of a metadata object.
void QTMetaDataRelease ( QTMetaDataRef inMetaData );
Discussion
This function releases a metadata object by decrementing its reference count. When the count becomes 0 the memory allocated to the object is freed and the object is destroyed. If you retain a metadata object you are responsible for releasing it when you no longer need it.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataRemoveItem
Removes a metadata item from a storage format.
OSStatus QTMetaDataRemoveItem ( QTMetaDataRef inMetaData, QTMetaDataItem inItem );
Parameters
- inMetaData
The metadata object for this operation.
- inItem
The opaque, unique
UInt64
identifier of the metadata item for this operation. Your application obtains this item identifier from such functions asQTMetaDataAddItem
andQTMetaDataGetNextItem
.
Return Value
Returns kQTMetaDataInvalidMetaDataErr
if
the metadata object or its reference is invalid, kQTMetaDataInvalidItemErr
if
the metatada item ID is invalid, or noErr
if
there is no error. See “Metadata Error Codes”
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataRemoveItemsWithKey
Removes metadata items with a specific key from the storage format.
OSStatus QTMetaDataRemoveItemsWithKey ( QTMetaDataRef inMetaData, QTMetaDataStorageFormat inMetaDataFormat, QTMetaDataKeyFormat inKeyFormat, const UInt8 *inKeyPtr, ByteCount inKeySize);
Parameters
- inMetaData
The metadata object for this operation.
- inMetaDataFormat
The metadata storage format used by the object passed in inMetaData. The format may be
UserData
storage, iTunes metadata storage, or QuickTime metadata storage. Not all objects will include all forms of storage, and other storage formats may appear in the future. You can passkQTMetaDataStorageFormatWildcard
to target all storage formats.- inKeyFormat
The format of the key.
- inKeyPtr
A pointer to the key of the item to be removed. You may pass
NULL
in this parameter if you want to remove all items.- inKeySize
The size of the key in bytes.
Return Value
Returns kQTMetaDataInvalidMetaDataErr
if
the metadata object or its reference is invalid, kQTMetaDataInvalidStorageFormatErr
if
the metatada storage format is invalid, kQTMetaDataInvalidKeyErr
if
the key or its format is invalid, or noErr
if
there is no error. See “Metadata Error Codes”
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataSetItem
Sets the value of the metadata item from the item identifier.
OSStatus QTMetaDataSetItem ( QTMetaDataRef inMetaData, QTMetaDataItem inItem, UInt8 *inValuePtr, ByteCount inValueSize, UInt32 inDataType);
Parameters
- inMetaData
The metadata object for this operation.
- inItem
The opaque, unique
UInt64
identifier of the metadata item for this operation. Your application obtains this item identifier from such functions asQTMetaDataAddItem
andQTMetaDataGetNextItem
.- inValuePtr
A pointer to the value to be set. This can be
NULL
if inValueSize is 0.- inValueSize
The size of inValuePtr in bytes. Pass 0 if you want to set an item with no value.
- inDataType
A data type from the following list:
kQTMetaDataTypeBinary = 0,
kQTMetaDataTypeUTF8 = 1,
kQTMetaDataTypeUTF16BE = 2,
kQTMetaDataTypeMacEncodedText = 3,
kQTMetaDataTypeSignedIntegerBE = 21,
kQTMetaDataTypeUnsignedIntegerBE = 22,
kQTMetaDataTypeFloat32BE = 23,
kQTMetaDataTypeFloat64BE = 24
With kQTMetaDataTypeSignedIntegerBE and kQTMetaDataTypeUnsignedIntegerBE, the size of the integer is determined by the value size.
Return Value
Returns kQTMetaDataInvalidMetaDataErr
if
the metadata object or its reference is invalid, kQTMetaDataInvalidItemErr
if
the metatada item ID is invalid, or noErr
if
there is no error. See “Metadata Error Codes”
.
Discussion
You can use this function to set the value of the metadata item with a given item identifier. You can set an item with an empty value by passing 0 in inValueSize.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataSetItemProperty
Sets a property of a metadata item.
OSStatus QTMetaDataSetItemProperty ( QTMetaDataRef inMetaData, QTMetaDataItem inItem, QTPropertyClass inPropClass, QTPropertyID inPropID, ByteCount inPropValueSize, ConstQTPropertyValuePtr inPropValueAddress );
Parameters
- inMetaData
The metadata object for this operation.
- inItem
The opaque, unique
UInt64
identifier of the metadata item for this operation. Your application obtains this item identifier from such functions asQTMetaDataAddItem
andQTMetaDataGetNextItem
.- inPropClass
The class of the property being set.
- inPropID
The ID of the property being set.
- inPropValueSize
Size of the buffer containing the property value being set.
- inPropValueAddress
A pointer to the buffer containing the item property value being set.
Return Value
Returns kQTMetaDataInvalidMetaDataErr
if
the metadata object or its reference is invalid, kQTMetaDataInvalidItemErr
if
the metatada item ID is invalid, errPropNotSupported
if
the metatada object does not support the property being set, qtReadOnlyErr
if
the property being set is read-only, or noErr
if
there is no error. See “Metadata Error Codes”
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTMetaDataSetProperty
Sets a property of a metadata object.
OSStatus QTMetaDataSetProperty ( QTMetaDataRef inMetaData, QTPropertyClass inPropClass, QTPropertyID inPropID, ByteCount inPropValueSize, ConstQTPropertyValuePtr inPropValueAddress);
Parameters
- inMetaData
The metadata object for this operation.
- inPropClass
The class of the property being set.
- inPropID
The ID of the property being set.
- inPropValueSize
Size of the buffer containing the property value being set.
- inPropValueAddress
A pointer to the buffer containing the property value being set.
Return Value
Returns kQTMetaDataInvalidMetaDataErr
if
the metadata object or its reference is invalid, errPropNotSupported
if
the metatada object does not support the property being set, qtReadOnlyErr
if
the property being set is read-only, or noErr
if
there is no error. See “Metadata Error Codes”
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTOpenGLTextureContextCreate
Creates a new OpenGL texture context for a specified OpenGL context and pixel format.
OSStatus QTOpenGLTextureContextCreate ( CFAllocatorRef allocator, CGLContextObj cglContext, CGLPixelFormatObj cglPixelFormat, CFDictionaryRef attributes, QTOpenGLTextureContextRef *newTextureContext );
Parameters
- allocator
The allocator used to create the texture context.
- cglContext
A pointer to an opaque
CGLPContextObj
structure representing the OpenGL context used to create textures. You can create this structure usingCGLCreateContext
.- cglPixelFormat
The pixel format object that specifies buffer types and other attributes of the new context.
- attributes
A dictionary of attributes.
- newTextureContext
A pointer to a variable to receive the new OpenGL texture 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:
ImageCompression.h
QTPixelBufferContextCreate
Creates a new pixel buffer context with the given attributes.
OSStatus QTPixelBufferContextCreate ( CFAllocatorRef allocator, CFDictionaryRef attributes, QTVisualContextRef *newPixelBufferContext );
Parameters
- allocator
Allocator used to create the pixel buffer context.
- attributes
Dictionary of attributes.
- newPixelBufferContext
Points to a variable to receive the new pixel buffer context.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This routine creates a new pixel buffer context with the given attributes.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
ImageCompression.h
QTRemoveTrackPropertyListener
Removes a track property monitoring callback
OSErr QTRemoveTrackPropertyListener ( Track inTrack, QTPropertyClass inPropClass, QTPropertyID inPropID, QTTrackPropertyListenerUPP inListenerProc, void *inUserData );
Parameters
- inTrack
The track for this operation.
- inPropClass
A property class.
- inPropID
A property ID.
- inListenerProc
A Universal Procedure Pointer to a QTTrackPropertyListenerProc callback.
- inUserData
User data to be passed to the callback.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This routine removes a track property monitoring callback.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableAddSampleDescription
Adds a sample description to a sample table, returning a sample description ID that can be used to refer to it.
OSStatus QTSampleTableAddSampleDescription ( QTMutableSampleTableRef sampleTable, SampleDescriptionHandle sampleDescriptionH, long mediaSampleDescriptionIndex, QTSampleDescriptionID *sampleDescriptionIDOut );
Parameters
- sampleTable
A reference to an opaque sample table object.
- sampleDescriptionH
A handle to a
SampleDescription
structure. QuickTime will make its own copy of this handle.- mediaSampleDescriptionIndex
The sample description index of this sample description in a media. Pass 0 for sample descriptions you add to sample tables, to indicate that this was not retrieved from a media.
- sampleDescriptionIDOut
A pointer to a variable to receive a sample description ID.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
You can use the returned sample description ID when adding samples to the sample table.
Special Considerations
Sample description IDs are local to each sample table. The same sample description handle may have different IDs when referenced in different sample tables.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableAddSampleReferences
Adds sample references to a sample table.
OSStatus QTSampleTableAddSampleReferences ( QTMutableSampleTableRef sampleTable, SInt64 dataOffset, ByteCount dataSizePerSample, TimeValue64 decodeDurationPerSample, TimeValue64 displayOffset, SInt64 numberOfSamples, MediaSampleFlags sampleFlags, QTSampleDescriptionID sampleDescriptionID, SInt64 *newSampleNumOut );
Parameters
- sampleTable
A reference to an opaque sample table object.
- dataOffset
A 64-bit signed integer that specifies the offset at which the first sample begins.
- dataSizePerSample
The number of bytes of data per sample. You must pass the data size per sample, not the total size of all the samples as with some other APIs.
- decodeDurationPerSample
A 64-bit time value that specifies the decode duration of each sample.
- displayOffset
A 64-bit time value that specifies the offset from decode time to display time of each sample. If the decode times and display times are the same, pass 0.
- numberOfSamples
A 64-bit signed integer, which must be greater than 0, that specifies the number of samples.
- sampleFlags
Flags that indicate the
sync
status of all samples:mediaSampleNotSync
If set to 1, indicates that the sample to be added is not a sync sample. Set this flag to 0 if the sample is a sync sample.
mediaSampleShadowSync
If set to 1, the sample is a shadow sync sample.
- sampleDescriptionID
The ID of a sample description that has been added to the sample table with
QTSampleTableAddSampleDescription
.- newSampleNumOut
A 64-bit signed integer that points to a variable to receive the sample number of the first sample that was added. Pass
NULL
if you don't want this information.
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
QTSampleTableCopySampleDescription
Retrieves a sample description from a sample table.
OSStatus QTSampleTableCopySampleDescription ( QTSampleTableRef sampleTable, QTSampleDescriptionID sampleDescriptionID, long *mediaSampleDescriptionIndexOut, SampleDescriptionHandle *sampleDescriptionHOut );
Parameters
- sampleTable
A reference to an opaque sample table object.
- sampleDescriptionID
The sample description ID.
- mediaSampleDescriptionIndexOut
A pointer to a variable to receive a media sample description index. If the sample description came from a media, this is the index that could be passed to
GetMediaSampleDescription
to retrieve the same sample description handle. The index will be 0 if the sample description did not come directly from a media. PassNULL
if you do not want to receive this information.- sampleDescriptionHOut
A pointer to a variable to receive a newly allocated sample description handle. Pass
NULL
if you do not want one. The caller is responsible for disposing the returned sample description handle usingDisposeHandle
.
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
QTSampleTableCreateMutable
Creates a new, empty sample table.
OSStatus QTSampleTableCreateMutable ( CFAllocatorRef allocator, TimeScale timescale, void *hints, QTMutableSampleTableRef *newSampleTable );
Parameters
- allocator
The allocator to use for the new sample table.
- timescale
A long integer that represents the timescale to use for durations and display offsets.
- hints
Reserved; pass
NULL
.- newSampleTable
A pointer to a variable that receives a new reference to an opaque sample table object.
Return Value
An error code. Returns memFullErr
if
it could not allocate memory, paramErr
if
the time scale is not positive or newSampleTable is NULL
,
or noErr
if there is no error.
Discussion
The newly created sample table contains no sample references. When sample references are added, their durations and display offsets are interpreted according to the sample table’s current timescale.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableCreateMutableCopy
Copies a sample table.
OSStatus QTSampleTableCreateMutableCopy ( CFAllocatorRef allocator, QTSampleTableRef sampleTable, void *hints, QTMutableSampleTableRef *newSampleTable );
Parameters
- allocator
The allocator to use for the new sample table.
- sampleTable
A reference to an opaque sample table object to copy.
- hints
Reserved; set to
NULL
.- newSampleTable
A pointer to a variable that receives a reference to an opaque sample table object.
Return Value
An error code. Returns memFullErr
if
it could not allocate memory, paramErr
if
the time scale is not positive or newSampleTable is NULL
,
or noErr
if there is no error.
Discussion
All the sample references and sample descriptions in the sample table are copied.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableGetDataOffset
Returns the data offset of a sample.
SInt64 QTSampleTableGetDataOffset ( QTSampleTableRef sampleTable, SInt64 sampleNum );
Parameters
- sampleTable
A reference to an opaque sample table object.
- sampleNum
A 64-bit signed integer that represents a sample number. The first sample’s number is 1.
Return Value
A 64-bit signed integer
that represents the offset to the sample. Returns 0 if sampleTable is NULL
or
if the sample number is out of range.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableGetDataSizePerSample
Returns the data size of a sample.
ByteCount QTSampleTableGetDataSizePerSample ( QTSampleTableRef sampleTable, SInt64 sampleNum );
Parameters
- sampleTable
A reference to an opaque sample table object.
- sampleNum
A 64-bit signed integer that represents the sample number. The first sample’s number is 1.
Return Value
The size of the sample
in bytes. Returns 0 if samplTable is NULL
or
if the sample number is out of range.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableGetDecodeDuration
Returns the decode duration of a sample.
TimeValue64 QTSampleTableGetDecodeDuration ( QTSampleTableRef sampleTable, SInt64 sampleNum );
Parameters
- sampleTable
A reference to an opaque sample table object.
- sampleNum
A 64-bit signed integer that represents the sample number. The first sample’s number is 1.
Return Value
A 64-bit time value
that represents the decode duration of the sample. Returns 0 if samplTable is NULL
or
if the sample number is out of range.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableGetDisplayOffset
Returns the offset from decode time to display time of a sample.
TimeValue64 QTSampleTableGetDisplayOffset ( QTSampleTableRef sampleTable, SInt64 sampleNum );
Parameters
- sampleTable
A reference to an opaque sample table object.
- sampleNum
A 64-bit signed integer that represents the sample number. The first sample’s number is 1.
Return Value
A 64-bit time value
that represents the offset from decode time to display time of the
sample. Returns 0 if samplTable is NULL
or
if the sample number is out of range.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableGetNextAttributeChange
Finds the next sample number at which one or more of a set of given sample attributes change.
OSStatus QTSampleTableGetNextAttributeChange ( QTSampleTableRef sampleTable, SInt64 startSampleNum, QTSampleTableAttribute attributeMask, SInt64 *sampleNumOut );
Parameters
- sampleTable
A reference to an opaque sample table object.
- startSampleNum
A 64-bit signed integer that contains the sample number to start searching from.
- attributeMask
An unsigned 32-bit integer that contains flags indicating which kinds of attribute changes to search for:
kQTSampleTableAttribute_DiscontiguousData = 1L << 0
Set this flag to find the first sample number num such that samples num-1 and num are not adjacent; that is,
dataOffset
ofnum-1 + dataSize
ofnum-1 != dataOffset
ofnum
.kQTSampleTableAttribute_DataSizePerSampleChange = 1L << 1
Set this flag to find the first sample with data size per sample different from that of the starting sample.
kQTSampleTableAttribute_DecodeDurationChange = 1L << 2
Set this flag to find the first sample with decode duration different from that of the starting sample.
kQTSampleTableAttribute_DisplayOffsetChange = 1L << 3
Set this flag to find the first sample with display offset different from that of the starting sample.
kQTSampleTableAttribute_SampleDescriptionIDChange = 1L << 4
Set this flag to find the first sample with sample description ID different from that of the starting sample.
kQTSampleTableAttribute_SampleFlagsChange = 1L << 5
Set this flag to find the first sample with any media sample flags different from those of the starting sample.
kQTSampleTableAnyAttributeChange = 0
If no flags are set, find the first sample with any attribute different from the starting sample.
- sampleNumOut
A 64-bit signed integer that points to a variable to receive the next sample number after startSampleNum at which any of the requested attributes change. If no attribute changes are found, this variable is set to 0.
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
QTSampleTableGetNumberOfSamples
Returns the number of samples in a sample table.
SInt64 QTSampleTableGetNumberOfSamples ( QTSampleTableRef sampleTable );
Parameters
- sampleTable
A reference to an opaque sample table object.
Return Value
A 64-bit signed integer
that contains the number of samples, or 0 if sampleTable is NULL
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableGetProperty
Returns the value of a specific sample table property.
OSStatus QTSampleTableGetProperty ( QTSampleTableRef sampleTable, QTPropertyClass inPropClass, QTPropertyID inPropID, ByteCount inPropValueSize, QTPropertyValuePtr outPropValueAddress, ByteCount *outPropValueSizeUsed );
Parameters
- sampleTable
A reference to an opaque sample table object.
- inPropClass
Pass the following constant to define the property class:
kQTPropertyClass_SampleTable = 'qtst'
Property of a sample table.
- inPropID
Pass one of these constants to define the property ID:
kQTSampleTablePropertyID_TotalDecodeDuration = 'tded'
The total decode duration of all samples in the sample table. Read-only.
kQTSampleTablePropertyID_MinDisplayOffset = '<ddd'
The least display offset in the table. Negative offsets are less than positive offsets. Read-only.
kQTSampleTablePropertyID_MaxDisplayOffset = '>ddd'
The greatest display offset in the table. Positive offsets are greater than negative offsets. Read-only.
kQTSampleTablePropertyID_MinRelativeDisplayTime = '<dis'
The least display time of all samples in the table, relative to the decode time of the first sample in the table. Read-only.
kQTSampleTablePropertyID_MaxRelativeDisplayTime = '>dis'
The greatest display time of all samples in the table, relative to the decode time of the first sample in the table. Read-only.
- inPropValueSize
The size of the buffer allocated to receive the property value.
- outPropValueAddress
A pointer to the buffer allocated to receive the property value.
- outPropValueSizeUsed
On return, the actual size of the property value written to the buffer.
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
QTSampleTableGetPropertyInfo
Returns information about the properties of a sample table.
OSStatus QTSampleTableGetPropertyInfo ( QTSampleTableRef sampleTable, QTPropertyClass inPropClass, QTPropertyID inPropID, QTPropertyValueType *outPropType, ByteCount *outPropValueSize, UInt32 *outPropertyFlags );
Parameters
- sampleTable
A reference to an opaque sample table object.
- inPropClass
Pass the following constant to define the property class:
kQTPropertyClass_SampleTable = 'qtst'
Property of a sample table.
- inPropID
Pass one of these constants to define the property ID:
kQTSampleTablePropertyID_TotalDecodeDuration = 'tded'
The total decode duration of all samples in the sample table. Read-only.
kQTSampleTablePropertyID_MinDisplayOffset = '<ddd'
The least display offset in the table. Negative offsets are less than positive offsets. Read-only.
kQTSampleTablePropertyID_MaxDisplayOffset = '>ddd'
The greatest display offset in the table. Positive offsets are greater than negative offsets. Read-only.
kQTSampleTablePropertyID_MinRelativeDisplayTime = '<dis'
The least display time of all samples in the table, relative to the decode time of the first sample in the table. Read-only.
kQTSampleTablePropertyID_MaxRelativeDisplayTime = '>dis'
The greatest display time of all samples in the table, relative to the decode time of the first sample in the table. Read-only.
- outPropType
A pointer to memory allocated to hold the property type on return: Pass
NULL
if you do not want this information.- outPropValueSize
A pointer to memory allocated to hold the size of the property value on return. Pass
NULL
if you do not want this information.- outPropertyFlags
A pointer to memory allocated to hold property flags on return. Pass
NULL
if you do not want this information.
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
QTSampleTableGetSampleDescriptionID
Returns the sample description ID of a sample.
QTSampleDescriptionID QTSampleTableGetSampleDescriptionID ( QTSampleTableRef sampleTable, SInt64 sampleNum );
Parameters
- sampleTable
A reference to an opaque sample table object.
- sampleNum
A 64-bit signed integer that represents the sample number. The first sample’s number is 1.
Return Value
The sample’s sample
description ID. Returns 0 if samplTable is NULL
or if
the sample number is out of range.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableGetSampleFlags
Returns the media sample flags of a sample.
MediaSampleFlags QTSampleTableGetSampleFlags ( QTSampleTableRef sampleTable, SInt64 sampleNum );
Parameters
- sampleTable
A reference to an opaque sample table object.
- sampleNum
A 64-bit signed integer that represents the sample number. The first sample’s number is 1.
Return Value
A constant that describes
characteristics of the sample (see below). Returns 0 if samplTable is NULL
or
if the sample number is out of range.
Discussion
This function can return one or more of the following constants:
mediaSampleNotSync
Sample is not a sync sample (for example, it is is frame differenced).
mediaSampleShadowSync
Sample is a shadow sync sample.
mediaSampleDroppable
Sample does not need to be decoded for later samples to be decoded properly.
mediaSamplePartialSync
Sample is a partial sync sample (for example, 1 frame after open GOP).
mediaSampleHasRedundantCoding
Sample is known to contain redundant coding.
mediaSampleHasNoRedundantCoding
Sample is known not to contain redundant coding.
mediaSampleIsDependedOnByOthers
One or more other samples depend on this sample being decoded.
mediaSampleIsNotDependedOnByOthers
Synonym for
mediaSampleDroppable
.mediaSampleDependsOnOthers
Decoding this sample depends on decoding other samples.
mediaSampleDoesNotDependOnOthers
Decoding this sample does not depend on decoding other samples.
mediaSampleEarlierDisplayTimesAllowed
Samples later in decode order may have earlier display times.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableGetTimeScale
Returns the timescale of a sample table.
TimeScale QTSampleTableGetTimeScale ( QTSampleTableRef sampleTable );
Parameters
- sampleTable
A reference to an opaque sample table object.
Return Value
A long integer that
represents the sample’s time scale, or 0 if sampleTable is NULL
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableGetTypeID
Returns the CFTypeID
value
for the current sample table.
CFTypeID QTSampleTableGetTypeID ( void );
Return Value
A CFTypeID
value.
Discussion
You could use this to test whether a CFTypeRef
that
was extracted from a CF container such as a CFArray
is
a QTSampleTableRef
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableRelease
Decrements the retain count of a sample table.
void QTSampleTableRelease ( QTSampleTableRef sampleTable );
Parameters
- sampleTable
A reference to an opaque sample table object. If you pass
NULL
in this parameter, nothing happens.
Discussion
If the retain count decreases to zero, the sample table is disposed.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableReplaceRange
Replaces a range of samples in a sample table with a range of samples from another sample table.
OSStatus QTSampleTableReplaceRange ( QTMutableSampleTableRef destSampleTable, SInt64 destStartingSampleNum, SInt64 destSampleCount, QTSampleTableRef sourceSampleTable, SInt64 sourceStartingSampleNum, SInt64 sourceSampleCount );
Parameters
- destSampleTable
A reference to an opaque sample table object to be modified.
- destStartingSampleNum
A 64-bit signed integer that represents the first sample number in destSampleTable to be replaced or deleted, or the sample number at which samples should be inserted.
- destSampleCount
A 64-bit signed integer that represents the number of samples to be removed from destSampleTable. Pass 0 to insert samples without removing samples.
- sourceSampleTable
A reference to an opaque sample table object from which samples should be copied, or
NULL
to delete samples.- sourceStartingSampleNum
A 64-bit signed integer that represents the first sample number to be copied. This parameter is ignored when deleting samples.
- sourceSampleCount
A 64-bit signed integer that represents the number of samples which should be copied. Pass 0 to delete samples.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This function removes destSampleCount samples from destSampleTable starting with destStartingSampleNum, and then inserts sourceSampleCount samples from sourceSampleTable starting with sourceStartingSampleNum where the removed samples were. Sample descriptions will be copied if necessary and new sample description IDs defined. This function can also be used to delete a range of samples, or to insert samples without removing any.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableRetain
Increments the retain count of a sample table.
QTSampleTableRef QTSampleTableRetain ( QTSampleTableRef sampleTable );
Parameters
- sampleTable
A reference to an opaque sample table object. If you pass
NULL
in this parameter, nothing happens.
Return Value
A pointer to the OpaqueQTSampleTable
structure
that is returned for your convenience, or NULL
if
the function fails.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSampleTableSetProperty
Sets the value of a specific sample table property.
OSStatus QTSampleTableSetProperty ( QTSampleTableRef sampleTable, QTPropertyClass inPropClass, QTPropertyID inPropID, ByteCount inPropValueSize, ConstQTPropertyValuePtr inPropValueAddress );
Parameters
- sampleTable
A reference to an opaque sample table object.
- inPropClass
Pass the following constant to define the property class:
kQTPropertyClass_SampleTable = 'qtst'
Property of a sample table.
- inPropID
Pass one of these constants to define the property ID:
kQTSampleTablePropertyID_TotalDecodeDuration = 'tded'
The total decode duration of all samples in the sample table. Read-only.
kQTSampleTablePropertyID_MinDisplayOffset = '<ddd'
The least display offset in the table. Negative offsets are less than positive offsets. Read-only.
kQTSampleTablePropertyID_MaxDisplayOffset = '>ddd'
The greatest display offset in the table. Positive offsets are greater than negative offsets. Read-only.
kQTSampleTablePropertyID_MinRelativeDisplayTime = '<dis'
The least display time of all samples in the table, relative to the decode time of the first sample in the table. Read-only.
kQTSampleTablePropertyID_MaxRelativeDisplayTime = '>dis'
The greatest display time of all samples in the table, relative to the decode time of the first sample in the table. Read-only.
- inPropValueSize
Pass the size of the property value.
- inPropValueAddress
Pass a const void pointer to the property value.
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
QTSampleTableSetTimeScale
Changes the timescale of a sample table.
OSStatus QTSampleTableSetTimeScale ( QTMutableSampleTableRef sampleTable, TimeScale newTimeScale );
Parameters
- sampleTable
A reference to an opaque sample table object.
- newTimeScale
A long integer whose value is the time scale to be set.
Return Value
An error code. Returns paramErr
if
the time scale is not positive or sampleTable is NULL
,
or noErr
if there is no error.
Discussion
The durations and display offsets of all the sample references in the sample table are scaled from the old timescale to the new timescale. No durations are scaled to a value less than 1. Display offsets are adjusted to avoid display time collisions.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSetTrackProperty
Sets the value of a specific track property.
OSErr QTSetTrackProperty ( Track inTrack, QTPropertyClass inPropClass, QTPropertyID inPropID, ByteCount inPropValueSize, ConstQTPropertyValuePtr inPropValueAddress );
Parameters
- inTrack
The track for this operation.
- inPropClass
A property class.
- inPropID
A property ID.
- inPropValueSize
The size of the property value.
- inPropValueAddress
A pointer to the the property value.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
This routine sets the value of a specific track property.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSoundDescriptionConvert
Converts a sound description from one version to another.
OSStatus QTSoundDescriptionConvert ( QTSoundDescriptionKind fromKind, SoundDescriptionHandle fromDescription, QTSoundDescriptionKind toKind, SoundDescriptionHandle *toDescription );
Parameters
- fromKind
Reserved. Set to
kSoundDescriptionKind_Movie_AnyVersion
.- fromDescription
A handle to the sound description to be converted.
- toKind
The version you want fromDescription to be.
- toDescription
A reference to the resulting
SoundDescription
structure. You must dispose of the reference usingDisposeHandle
.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
The fromKind parameter is reserved
for future expansion; at present you must set it to kSoundDescriptionKind_Movie_AnyVersion
.
Depending on the value you pass in toKind, you
can specify that you would like a specific SoundDescription
version,
the lowest possible version (given the constraints of the format
described by fromDescription), or any
version at all.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSoundDescriptionCreate
Creates a sound description structure of the requested
kind from an AudioStreamBasicDescription
,
optional audio channel layout, and optional magic cookie.
OSStatus QTSoundDescriptionCreate ( AudioStreamBasicDescription *inASBD, AudioChannelLayout *inLayout, ByteCount inLayoutSize, void *inMagicCookie ByteCount inMagicCookieSize QTSoundDescriptionKind inRequestedKind SoundDescriptionHandle *outSoundDesc );
Parameters
- inASBD
A description of the format.
- inLayout
The audio channel layout (can be
NULL
if there isn’t one).- inLayoutSize
The size of the audio channel layout (should be 0 if inLayout is
NULL
).- inMagicCookie
The magic cookie for the decompressor (can be
NULL
if the decompressor doesn’t require one).- inMagicCookieSize
The size of the magic cookie (should be 0 if the inMagicCookie parameter is
NULL
).- inRequestedKind
The kind of sound description to create.
- outSoundDesc
The resulting sound description. The caller must dispose of it with
DisposeHandle
.
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
QTSoundDescriptionGetPropertyInfo
Gets information about a particular property of a sound description.
OSStatus QTSoundDescriptionGetPropertyInfo ( SoundDescriptionHandle inDesc, QTPropertyClass inPropClass, QTPropertyID inPropID, QTPropertyValueType *outPropType, ByteCount *outPropValueSize, UInt32 *outPropertyFlags);
Parameters
- inDesc
The sound description being interrogated.
- inPropClass
The class of the property being requested.
- inPropID
The ID of the property being requested.
- outPropType
The type of the property returned here (can be
NULL
).- outPropValueSize
The size of the property returned here (can be
NULL
).- outPropertyFlags
The property flags returned here (can be
NULL
).
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
The following constants identify sound description properties.
enum { |
kQTSoundDescriptionPropertyID_AudioChannelLayout = 'clay', |
kQTSoundDescriptionPropertyID_MagicCookie = 'kuki', |
kQTSoundDescriptionPropertyID_AudioStreamBasicDescription = 'asbd', |
kQTSoundDescriptionPropertyID_UserReadableText = 'text' |
}; |
Special Considerations
kQTSoundDescriptionPropertyID_AudioChannelLayout = 'clay'
Used to get or set an
AudioChannelLayout
value. This is a variable-size property because it may contain an array of Channel Descriptions. You must get the size by callingQTSoundDescriptionGetPropertyInfo
, allocate a structure of that size, and then get the property.kQTSoundDescriptionPropertyID_MagicCookie = 'kuki'
Used to get or set opaque bytes. This is a variable-size property, because it is completely defined by the codec that uses the cookie. You must get the size by calling
QTSoundDescriptionGetPropertyInfo
, allocate a structure of that size, and then get the property.kQTSoundDescriptionPropertyID_AudioStreamBasicDescription = 'asbd'
Used to get an
AudioStreamBasicDescription
value.kQTSoundDescriptionPropertyID_UserReadableText = 'text'
Used to get a
CFStringRef
value.QTSoundDescriptionGetProperty
does aCFRetain
of the returnedCFString
on behalf of the caller, so the caller is responsible for callingCFRelease
on the returnedCFString
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSoundDescriptionGetProperty
Gets a particular property of a sound description.
OSStatus QTSoundDescriptionGetProperty ( SoundDescriptionHandle inDesc, QTPropertyClass inPropClass, QTPropertyID inPropID, ByteCount inPropValueSize, QTPropertyValuePtr outPropValueAddress, ByteCount *outPropValueSizeUsed);
Parameters
- inDesc
The sound description being interrogated.
- inPropClass
The class of the property being requested.
- inPropID
The ID of the property being requested.
- inPropValueSize
The size of the property value buffer.
- outPropValueAddress
A pointer to the property value buffer.
- outPropValueSizeUsed
The actual size of the returned property value (can be
NULL
).
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
The following constants identify sound description properties.
enum { |
kQTSoundDescriptionPropertyID_AudioChannelLayout = 'clay', |
kQTSoundDescriptionPropertyID_MagicCookie = 'kuki', |
kQTSoundDescriptionPropertyID_AudioStreamBasicDescription = 'asbd', |
kQTSoundDescriptionPropertyID_UserReadableText = 'text' |
}; |
Special Considerations
kQTSoundDescriptionPropertyID_AudioChannelLayout = 'clay'
Used to get or set an
AudioChannelLayout
value. This is a variable-size property because it may contain an array of Channel Descriptions. You must get the size by callingQTSoundDescriptionGetPropertyInfo
, allocate a structure of that size, and then get the property.kQTSoundDescriptionPropertyID_MagicCookie = 'kuki'
Used to get or set opaque bytes. This is a variable-size property, because it is completely defined by the codec that uses the cookie. You must get the size by calling
QTSoundDescriptionGetPropertyInfo
, allocate a structure of that size, and then get the property.kQTSoundDescriptionPropertyID_AudioStreamBasicDescription = 'asbd'
Used to get an
AudioStreamBasicDescription
value.kQTSoundDescriptionPropertyID_UserReadableText = 'text'
Used to get a
CFStringRef
value.QTSoundDescriptionGetProperty
does aCFRetain
of the returnedCFString
on behalf of the caller, so the caller is responsible for callingCFRelease
on the returnedCFString
.kQTAudioPropertyID_FormatString = 'fstr'
Used with
kQTPropertyClass_Audio
to get aCFStringRef
value containing a localized, human readable string that describes an audio format; for example, “MPEG Layer 3.” You may get this property from aSoundDescription
handle by callingQTSoundDescriptionGetProperty
or from aStandardAudioCompression
(scdi
oraudi
) component instance by callingQTGetComponentProperty
.kQTAudioPropertyID_ChannelLayoutString = 'lstr'
Used with
kQTPropertyClass_Audio
to get aCFStringRef
value containing a localized, human readable string that describes an audio channel layout; for example, “5.0 (L R C Ls Rs).” You may get this property from aSoundDescription
handle by callingQTSoundDescriptionGetProperty
or from aStandardAudioCompression
(scdi
oraudi
) component instance by callingQTGetComponentProperty
.kQTAudioPropertyID_SampleRateString = 'rstr'
Used to get a
CFStringRef
value containing a localized, human readable string that describes an audio sample rate; for example, “44.100 kHz.” You may get this property from aSoundDescription
handle by callingQTSoundDescriptionGetProperty
or from aStandardAudioCompression
(scdi
oraudi
) component instance by callingQTGetComponentProperty
.kQTAudioPropertyID_SampleSizeString = 'sstr'
Used to get a
CFStringRef
value containing a localized, human readable string that describes an audio sample size; for example, “24-bit.” This property will return a valid string only if the audio format is uncompressed (LPCM). You may get this property from aSoundDescription
handle by callingQTSoundDescriptionGetProperty
or from aStandardAudioCompression
(scdi
oraudi
) component instance by callingQTGetComponentProperty
.kQTAudioPropertyID_BitRateString = 'bstr'
Used to get a
CFStringRef
value containing a localized, human readable string that describes an audio bit rate; for example, “12 kbps.” You may get this property from aStandardAudioCompression
(scdi
oraudi
) component instance by callingQTGetComponentProperty
.kQTAudioPropertyID_SummaryString = 'asum'
Used to get a
CFStringRef
value containing a localized, human readable string that summarizes an audio format; for example, “16-bit Integer (Big Endian), Stereo (L R), 48.000 kHz.” You may get this property from aSoundDescription
handle by callingQTSoundDescriptionGetProperty
or from aStandardAudioCompression
(scdi
oraudi
) component instance by callingQTGetComponentProperty
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
QTSoundDescriptionSetProperty
Sets a particular property of a sound description.
OSStatus QTSoundDescriptionSetProperty ( SoundDescriptionHandle inDesc, QTPropertyClass inPropClass, QTPropertyID inPropID, ByteCount inPropValueSize, ConstQTPropertyValuePtr inPropValueAddress );
Parameters
- inDesc
The sound description being modified.
- inPropClass
The class of the property being set.
- inPropID
The ID of the property being set.
- inPropValueSize
The size of the property value buffer.
- inPropValueAddress
A pointer to the property value buffer.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
The following constants identify sound description properties.
enum { |
kQTSoundDescriptionPropertyID_AudioChannelLayout = 'clay', |
kQTSoundDescriptionPropertyID_MagicCookie = 'kuki', |
kQTSoundDescriptionPropertyID_AudioStreamBasicDescription = 'asbd', |
kQTSoundDescriptionPropertyID_UserReadableText = 'text' |
}; |
Special Considerations
kQTSoundDescriptionPropertyID_AudioChannelLayout = 'clay'
Used to get or set an
AudioChannelLayout
value. This is a variable-size property because it may contain an array of Channel Descriptions. You must get the size by callingQTSoundDescriptionGetPropertyInfo
, allocate a structure of that size, and then get the property.kQTSoundDescriptionPropertyID_MagicCookie = 'kuki'
Used to get or set opaque bytes. This is a variable-size property, because it is completely defined by the codec that uses the cookie. You must get the size by calling
QTSoundDescriptionGetPropertyInfo
, allocate a structure of that size, and then get the property.kQTSoundDescriptionPropertyID_AudioStreamBasicDescription = 'asbd'
Used to get an
AudioStreamBasicDescription
value.kQTSoundDescriptionPropertyID_UserReadableText = 'text'
Used to get a
CFStringRef
value.QTSoundDescriptionGetProperty
does aCFRetain
of the returnedCFString
on behalf of the caller, so the caller is responsible for callingCFRelease
on the returnedCFString
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
SampleNumToMediaDecodeTime
Finds the decode time for a specified sample.
void SampleNumToMediaDecodeTime ( Media theMedia, SInt64 logicalSampleNum, TimeValue64 *sampleDecodeTime, TimeValue64 *sampleDecodeDuration );
Parameters
- theMedia
The media for this operation. You obtain this media identifier from such functions as
NewTrackMedia
andGetTrackMedia
.- logicalSampleNum
A 64-bit signed integer that contains the sample number.
- sampleDecodeTime
A pointer to a time value. The function updates this time value to indicate the decode time of the sample specified by the logicalSampleNum parameter. This time value is expressed in the media's time scale. Set this parameter to
NULL
if you do not want this information.- sampleDecodeDuration
A pointer to a time value. The function updates this time value to indicate the decode duration of the sample specified by the logicalSampleNum parameter. This time value is expressed in the media's time scale. Set this parameter to
NULL
if you do not want this information.
Discussion
You can access this function’s error returns through GetMoviesError
and GetMoviesStickyError
.
It returns paramErr
if there is a bad
parameter value, or noErr
if there
is no error.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
SampleNumToMediaDisplayTime
Finds the display time for a specified sample.
void SampleNumToMediaDisplayTime ( Media theMedia, SInt64 logicalSampleNum, TimeValue64 *sampleDisplayTime, TimeValue64 *sampleDisplayDuration );
Parameters
- theMedia
The media for this operation. You obtain this media identifier from such functions as
NewTrackMedia
andGetTrackMedia
.- logicalSampleNum
A 64-bit signed integer that contains the sample number.
- sampleDisplayTime
A pointer to a time value. The function updates this time value to indicate the display time of the sample specified by the logicalSampleNum parameter. This time value is expressed in the media's time scale. Set this parameter to
NULL
if you do not want this information.- sampleDisplayDuration
A pointer to a time value. The function updates this time value to indicate the display duration of the sample specified by the logicalSampleNum parameter. This time value is expressed in the media’s time scale. Set this parameter to
NULL
if you do not want this information.
Discussion
You can access this function’s error returns through GetMoviesError
and GetMoviesStickyError
.
It returns paramErr
if there is a bad
parameter value, or noErr
if there
is no error.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
SCAudioInvokeLegacyCodecOptionsDialog
Invokes the legacy code options dialog of an audio codec component.
ComponentResult SCAudioInvokeLegacyCodecOptionsDialog ( ComponentInstance ci );
Parameters
- ci
A component instance that identifies a connection to an audio codec component.
Return Value
An error code, or noErr
if
there is no error.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
QuickTimeComponents.h
SCCopyCompressionSessionOptions
Creates a compression session options object based upon the settings in the Standard Compression component.
ComponentResult SCCopyCompressionSessionOptions ( ComponentInstance ci, ICMCompressionSessionOptionsRef *outOptions );
Parameters
- ci
A component instance of Standard Compression component.
- outOptions
On return, a reference to a new compression session options object.
Return Value
An error code. Returns noErr
if
there is no error. paramErr if
the client did not set the scAllowEncodingWithCompressionSession
preference
flag.
Discussion
This function creates a new compression session options object
using the compression settings of the Standard Compression component
instance. You can use other Standard Compression component calls
to set up the compression settings. Then you call this function
to extract the compression settings in the form of a compression
session options object. The returned object can be used to create
a compression session object through ICMCompressionSessionCreate()
.
The caller must indicate that he or she intends to use the
new ICM compression session API to perform the compression operation,
by setting the scAllowEncodingWithCompressionSession
preference
flag through SCSetInfo()
with
the scPreferenceFlagsType
selector.
The caller of this function is expected to release the returned
compression session options object through ICMCompressionSessionOptionsRelease
when
it is done.
Version Notes
Introduced in QuickTime 7
Availability
- Carbon status: Supported
C interface file:
QuickTimeComponents.h
SetDSequenceNonScheduledDisplayDirection
Sets the display direction for a decompress sequence.
OSErr SetDSequenceNonScheduledDisplayDirection ( ImageSequence sequence, Fixed rate );
Parameters
- sequence
Contains the unique sequence identifier that was returned by the
DecompressSequenceBegin
function.- rate
The display direction to be set. 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:
QuickTimeComponents.h
SetDSequenceNonScheduledDisplayTime
Sets the display time for a decompression sequence.
OSErr SetDSequenceNonScheduledDisplayTime ( ImageSequence sequence, TimeValue64 displayTime, TimeScale displayTimeScale, UInt32 flags );
Parameters
- sequence
Contains the unique sequence identifier that was returned by the
DecompressSequenceBegin
function.- displayTime
The display time to be set.
- displayTimeScale
The display time scale to be set.
- flags
Not used; set to 0.
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:
QuickTimeComponents.h
SetMovieAudioBalance
Sets the balance level for the mixed audio output of a movie.
OSStatus SetMovieAudioBalance ( 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
, andNewMovieFromHandle
.- leftRight
A pointer to the new 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 GetMovieAudioBalance
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
SetMovieAudioContext
Targets a movie to render into an audio context.
OSStatus SetMovieAudioContext ( Movie movie, QTAudioContextRef audioContext;
Parameters
- movie
The movie.
- audioContext
The audio context that the movie will render into.
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
SetMovieAudioFrequencyMeteringNumBands
Configures frequency metering for a particular audio mix in a movie.
OSStatus SetMovieAudioFrequencyMeteringNumBands ( Movie m, FourCharCode whatMixToMeter, UInt32 *ioNumBands );
Parameters
- m
The movie for this operation. Your application obtains this movie identifier from such functions as
NewMovie
,NewMovieFromProperties
,NewMovieFromFile
, andNewMovieFromHandle
.- whatMixToMeter
The applicable mix of audio channels in the movie; see
“Movie Audio Mixes”
.- ioNumBands
A pointer to memory that stores the number of bands being metered. On calling this function, you specify the number of frequency bands you want to meter. If that number is higher than is possible (determined by factors such as the sample rate of the audio being metered), the function will return the number of bands it is actually going to meter. You can pass
NIL
or a pointer to 0 to disable metering.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
SetMovieAudioGain
Sets the audio gain level for the mixed audio output of a movie, altering the perceived volume of the movie’s playback.
OSStatus SetMovieAudioGain ( 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
, andNewMovieFromHandle
.- 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 GetMovieAudioGain
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
SetMovieAudioMute
Sets the mute value for the audio mix of a movie currently playing.
OSStatus SetMovieAudioMute ( 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
, andNewMovieFromHandle
.- muted
Pass
TRUE
to mute the movie audio,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 GetMovieAudioMute
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
SetMovieAudioVolumeMeteringEnabled
Enables or disables volume metering of a particular audio mix of a movie.
OSStatus SetMovieAudioVolumeMeteringEnabled ( 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
, andNewMovieFromHandle
.- whatMixToMeter
The applicable mix of audio channels in the movie; see
“Movie Audio Mixes”
.- enabled
Pass
TRUE
to enable audio volume metering; passFALSE
to disable it.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
SetTrackAudioGain
Sets the audio gain level for the audio output of a track, altering the perceived volume of the track’s playback.
OSStatus SetTrackAudioGain ( Track t, Float32 gain, UInt32 flags );
Parameters
- t
A track identifier, which your application obtains from such functions as
NewMovieTrack
andGetMovieTrack
.- 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’s gain setting is not stored in the movie; it
is used only until the movie is closed. See GetTrackAudioGain
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
SetTrackAudioMute
Mutes or unmutes the audio output of a track.
OSStatus SetTrackAudioMute ( Track t, Boolean muted, UInt32 flags );
Parameters
- t
A track identifier, which your application obtains from such functions as
NewMovieTrack
andGetMovieTrack
.- muted
Pass
TRUE
to mute the track’s audio,FALSE
to unmute it.- flags
Not used; set to 0.
Return Value
An error code. Returns noErr
if
there is no error.
Discussion
The track mute setting is not stored in the movie; it is used
only until the movie is closed. See GetTrackAudioMute
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported
C interface file:
Movies.h
TrackTimeToMediaDisplayTime
Converts a track’s time value to a display time value that is appropriate to the track’s media, using the track’s edit list.
TimeValue64 TrackTimeToMediaDisplayTime ( TimeValue64 value, Track theTrack );
Parameters
- value
A 64-bit time value that represents the track’s time value; it must be expressed in the time scale of the movie that contains the track.
- theTrack
A track identifier, which your application obtains from such functions as
NewMovieTrack
andGetMovieTrack
.
Return Value
A 64-bit time value that represents the corresponding time in media display time, in the media's time coordinate system. If the track time corresponds to empty space, this function returns a value of –1.
Discussion
This function maps the track time through the track’s edit list to come up with the media time. This time value contains the track’s time value according to the media’s time coordinate system. If the time you specified lies outside of the movie’s active segment or corresponds to empty space in the track, this function returns a value of –1. Hence you can use it to determine whether a specified track edit is empty.
Version Notes
Introduced in QuickTime 7. This function is a 64-bit replacement
for TrackTimeToMediaTime
.
Availability
- Carbon status: Supported
C interface file:
Movies.h
Callbacks
The callback functions new to the QuickTime 7 API are documented alphabetically in this section.
ICMDecompressionTrackingCallbackProc
The callback through which a client of an ICM decompression session receives decoded frames and information about decoding.
typedef void (*ICMDecompressionTrackingCallback)( void *decompressionTrackingRefCon, OSStatus result, ICMDecompressionTrackingFlags decompressionTrackingFlags, CVPixelBufferRef pixelBuffer, TimeValue64 displayTime, TimeValue64 displayDuration, ICMValidTimeFlags validTimeFlags, void *sourceFrameRefCon, void *reserved); // Declaration of a typical application-defined function Boolean MyICMDecompressionTrackingCallbackProc ( void *decompressionTrackingRefCon, OSStatus result, ICMDecompressionTrackingFlags decompressionTrackingFlags, CVPixelBufferRef pixelBuffer, TimeValue64 displayTime, TimeValue64 displayDuration, ICMValidTimeFlags validTimeFlags, void *sourceFrameRefCon, void *reserved );
Parameters
- decompressionTrackingRefCon
The callback’s reference value, copied from the decompressionTrackingRefCon field of an
ICMDecompressionTrackingCallbackRecord
structure.- result
Indicates whether there was an error in decompression.
- decompressionTrackingFlags
One or more flags describing the a frame's state transitions:
kICMDecompressionTracking_LastCall = 1L<<0
This is the last call for this sourceFrameRefCon.
kICMDecompressionTracking_ReleaseSourceData = 1L<<1
The session no longer needs the source data pointer.
kICMDecompressionTracking_EmittingFrame = 1L<<2
A frame is being emitted. The pixelBuffer parameter contains the decompressed frame. If the decompression session is targetting a visual context, the frame has not yet been sent to the visual context but will be sent after the callback returns.
kICMDecompressionTracking_FrameDecoded = 1L<<3
This frame was decoded.
kICMDecompressionTracking_FrameDropped = 1L<<4
The codec decided to drop this frame.
kICMDecompressionTracking_FrameNeedsRequeueing = 1L<<5
This frame will not be able to be displayed unless it is queued for redecode ( this constant is also known as
FrameNotDisplayable
).
- pixelBuffer
When the
kICMDecompressionTracking_EmittingFrame
flag is set in decompressionTrackingFlags, this parameter must reference a pixel buffer containing the decompressed frame.- displayTime
If
kICMValidTime_DisplayTimeStampIsValid
is set in validTimeFlags, this parameter must pass the display time of the frame.- displayDuration
If
kICMValidTime_DisplayDurationIsValid
is set in validTimeFlags, this parameter must pass the display duration of the frame.- validTimeFlags
Indicates which of displayTime and displayDuration is valid:
kICMValidTime_DisplayTimeStampIsValid
The time value passed in displayTimeStamp is valid.
kICMValidTime_DisplayDurationIsValid
The time value passed in displayDuration is valid.
- sourceFrameRefCon
The frame’s reference value, copied from the sourceFrameRefCon parameter passed to
ICMDecompressionSessionDecodeFrame
.- reserved
Reserved for future use.
Discussion
This callback is referenced by an ICMDecompressionTrackingCallbackRecord
.
MovieExportStageReachedCallbackProc
Installed by NewMovieExportStageReachedCallbackUPP
.
typedef OSErr (*MovieExportStageReachedCallbackProcPtr)(OSType inStage, Movie inMovie, ComponentInstance inDataHandler, Handle inDataRef, OSType inDataRefType, void *refCon); // Declaration of a typical application-defined function Boolean MyMovieExportStageReachedCallbackProc ( OSType inStage, Movie inMovie, ComponentInstance inDataHandler, Handle inDataRef, OSType inDataRefType, void *refCon );
Parameters
- inStage
A movie export stage.
- inMovie
A movie.
- inDataHandler
A data handler component.
- inDataRef
A handle to a data reference.
- inDataRefType
The type of the data reference.
- refCon
A reference constant to be passed to the callback specified in
NewMovieExportStageReachedCallbackUPP
. Use this parameter to point to a data structure containing any information your callback needs.
SGAudioCallbackProc
Provides access to a SGAudioMediaType
channel’s
data at various point along the signal flow.
typedef OSStatus (*SGAudioCallbackProcPtr) (SGChannel c, void *inRefCon, SGAudioCallbackFlags *ioFlags, const AudioTimeStamp *inTimeStamp, const UInt32 *inNumberPackets, const AudioBufferList *inData, const AudioStreamPacketDescription *inPacketDescriptions); // Declaration of a typical application-defined function OSStatus MySGAudioCallbackProc ( SGChannel c, void *inRefCon, SGAudioCallbackFlags *ioFlags, const AudioTimeStamp *inTimeStamp, const UInt32 *inNumberPackets, const AudioBufferList *inData, const AudioStreamPacketDescription *inPacketDescriptions );
Parameters
- c
The sequence grabber channel that has originating this callback.
- inRefCon
A reference constant passed by the caller. Use this parameter to point to a data structure containing any information your callback needs.
- ioFlags
Currently not used.
- inTimeStamp
The time stamp associated with the first sample passed in inData.
- inNumberPackets
The number of data packets held in inData. With LPCM formats the number of packets is the same as number of frames.
- inData
A bufferlist containing the requested sample data.
- inPacketDescriptions
If the packets contained in inData are of variable size, this parameter should pass an array of inNumberPackets packet descriptions.
Discussion
Use QTSetComponentProperty
with kQTPropertyClass_SGAudio
and
any of the following property IDs to specify which callback you
would like to receive:
kQTSGAudioPropertyID_PreMixCallback
kQTSGAudioPropertyID_PostMixCallback
kQTSGAudioPropertyID_PreConversionCallback
kQTSGAudioPropertyID_PostConversionCallback
Pass an SGAudioCallbackStruct
as
the data payload. Clients define an SGAudioCallbackProc
in
order to tap into a SGAudioMediaType
channel,
gaining access to its data at various points along the signal flow
chain. Clients should be aware that they may be called back on threads
other than the thread on which they registered for the callback.
They should do as little work as possible inside their callback,
returning control as soon as possible to the channel.
QTOpenGLTextureAvailableCallbackProc
Receives notifications when a new OpenGL texture becomes available.
typedef void (*QTOpenGLTextureAvailableCallback)( QTOpenGLTextureContextRef textureContext, const CVTimeStamp *timeStamp, void *refCon ); // Declaration of a typical application-defined function OSStatus MyQTOpenGLTextureAvailableCallback ( QTOpenGLTextureContextRef textureContext, const CVTimeStamp *timeStamp, void *refCon );
Parameters
- textureContext
The OpenGL texture context invoking the callback.
- timeStamp
Time for which a new texture has become available.
- refCon
A reference constant passed by the caller. Use this parameter to point to a data structure containing any information your callback needs.
Discussion
Due to unpredictible activity, such as user seeks or the arrival of streaming video packets from a network, new textures may become available for times supposedly occupied by previous textures. Responsive applications, therefore, should use this callback to discover as soon as possible when a movie needs to be updated.
Data Structures
The public data structures new to the QuickTime 7 API are documented alphabetically in this section. Certain other data structures are referenced by QuickTime 7 functions but are opaque.
ICMDecompressionTrackingCallbackRecord
Designates a tracking callback for an ICM decompression session.
struct ICMDecompressionTrackingCallbackRecord { ICMDecompressionTrackingCallback decompressionTrackingCallback; void *decompressionTrackingRefCon; };
Fields
decompressionTrackingCallback
The callback function pointer. See
ICMDecompressionTrackingCallbackProc
.decompressionTrackingRefCon
The callback’s reference value.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported;
C interface file:
ImageCompression.h
ICMMultiPassStorageCallbacks
Designates a collection of callbacks for creating a custom multipass storage object.
struct ICMMultiPassStorageCallbacks { UInt32 version; void *storageRefCon; ICMMultiPassSetDataAtTimeStampCallback setDataAtTimeStampCallback; ICMMultiPassGetTimeStampCallback getTimeStampCallback; ICMMultiPassCopyDataAtTimeStampCallback copyDataAtTimeStampCallback; ICMMultiPassReleaseCallback releaseCallback; };
Fields
version
The version of this structure. Set to
kICMMultiPassStorageCallbacksVersionOne
.storageRefCon
A pointer to a reference constant. Use this parameter to point to a data structure containing any information your callback needs.
setDataAtTimeStampCallback
A callback for storing values.
getTimeStampCallback
A callback for finding time stamps.
copyDataAtTimeStampCallback
A callback for retrieving values.
releaseCallback
A callback for disposing the callback's state when done.
Discussion
This structure is used by ICMMultiPassStorageCreateWithCallbacks
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported;
C interface file:
ImageCompression.h
QTAudioFrequencyLevels
Stores the frequency meter level settings for the audio channels in a movie mix.
struct QTAudioFrequencyLevels { UInt32 numChannels; UInt32 numFrequencyBands; Float32 level[1]; };
Fields
numChannels
The number of audio channels.
numFrequencyBands
The number of frequency bands for each channel.
level
A 32-bit floating-point value for each frequency band. The frequency bands for each channel are stored contiguously, with all the band levels for the first channel first, all the band levels for the second channel next, etc. The total number of 32-bit values in this field equals
numFrequencyBands
timesnumChannels
.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported;
C interface file:
Movies.h
Platform Considerations
Associated function: GetMovieAudioFrequencyLevels
QTAudioVolumeLevels
Stores the volume level settings for the audio channels in a movie mix.
struct QTAudioVolumeLevels { UInt32 numChannels; Float32 level; };
Fields
numChannels
The number of audio channels.
level
A 32-bit floating-point value for each channel’s volume.
Discussion
Note that these are variable-sized structures that must be allocated large enough.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported;
C interface file:
Movies.h
Platform Considerations
Associated function: GetMovieAudioVolumeLevels
QTNewMoviePropertyElement
Stores a movie property for NewMovieFromProperties
.
struct QTNewMoviePropertyElement { QTPropertyClass propClass; QTPropertyID propID; ByteCount propValueSize; QTPropertyValuePtr propValueAddress; OSStatus propStatus; };
Fields
propClass
A four-character code designating the class of a movie property. See New Movie Property Codes.
propID
The ID of the property.
propValueSize
The size in bytes of the property passed in
propValueAddress
.propValueAddress
A pointer to a movie property. Since the data type is fixed for each element’s property class and ID, these is no ambiguity about the data type for its property value.
propStatus
Indicates any problems with the property. For example, if a property is not understood by the function it is passed to, this field is set appropriately. See the discussion in
NewMovieFromProperties
.
Discussion
When you call NewMovieFromProperties
,
you allocate and own arrays of these elements to pass to it, as
well as the property values that each element points to. You are
responsible for disposing of all of these memory allocations.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported;
C interface file:
Movies.h
Platform Considerations
Associated function: NewMovieFromProperties
SGAudioCallbackStruct
Used to call an SGAudioCallbackProc
.
struct SGAudioCallbackStruct { SGAudioCallback inputProc; void *inputProcRefCon; };
Fields
inputProc
inputProcRefCon
A reference constant. Use this parameter to point to a data structure containing any information your callback needs.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported;
C interface file:
Movies.h
SoundDescriptionV2
Provides version 2 of the SoundDescription
data
structure.
struct SoundDescriptionV2 { SInt32 descSize; OSType dataFormat; SInt32 resvd1; SInt16 resvd2; SInt16 dataRefIndex; SInt16 version; SInt16 revlevel; SInt32 vendor; SInt16 always3; SInt16 always16; SInt16 alwaysMinus2; SInt16 always0; UInt32 always65536; UInt32 sizeOfStructOnly; Float64 audioSampleRate; UInt32 numAudioChannels; SInt32 always7F000000; UInt32 constBitsPerChannel; UInt32 formatSpecificFlags; UInt32 constBytesPerAudioPacket; UInt32 constLPCMFramesPerAudioPacket; /* additional atom-based extensions ([long size, long type, some data], repeat) */ };
Fields
descSize
Total size of this structure, including extra data.
dataFormat
Set to
'lpcm'
for uncompressed data; otherwise set to the compression type. For a list of compression type codes, see the QuickTime API Reference.resvd1
Reserved; set to 0.
resvd2
Reserved; set to 0.
dataRefIndex
Reserved; set to 0.
version
Version of this structure; set to 2.
revlevel
Set to codec version number.
always3
Reserved; set to 3.
always16
Reserved; set to 16 (0x0010).
alwaysMinus2
Reserved; set to –2 (0xFFFE).
always0
Reserved; set to 0.
always65536
Reserved; set to 65536 (0x00010000).
sizeOfStructOnly
Set to
sizeof(SoundDescriptionV2)
, equivalent to the offset to any structure extensions.audioSampleRate
Set to a 64-bit floating-point number representing the number of audio frames per second; for example, 44100.0.
numAudioChannels
Set to the number of audio channels; any channel assignment info will be in an extension.
always7F000000
Reserved; set to 7F000000.
constBitsPerChannel
Set to the number of bits per channel only if this value is constant and the audio is uncompressed. Otherwise set to 0.
formatSpecificFlags
See LPCM flag definitions in
CoreAudioTypes.h
.constBytesPerAudioPacket
Set to the number of bytes per packet only if this value is constant. Otherwise set to 0.
constLPCMFramesPerAudioPacket
Set to the number of PCM frames per packet only if this value is constant. Otherwise set to 0.
Version Notes
Introduced in QuickTime 7.
Availability
- Carbon status: Supported;
C interface file:
Movies.h
Platform Considerations
You should never have to know this definition, except for debugging purposes. Use the new QuickTime sound description APIs to treat sound descriptions as if they are opaque.
Constants
This section lists constants that are newly defined in QuickTime 7.
ICM Compression Session Options
The following values are used to select options for ICM compression session objects:
kQTPropertyClass_ICMCompressionSessionOptions = 'icso', |
kICMCompressionSessionOptionsPropertyID_AllowAsyncCompletion = 'asok', |
kICMCompressionSessionOptionsPropertyID_AllowFrameReordering = 'b ok', |
kICMCompressionSessionOptionsPropertyID_AllowFrameTimeChanges = '+ ok', |
kICMCompressionSessionOptionsPropertyID_AllowTemporalCompression = 'p ok', |
kICMCompressionSessionOptionsPropertyID_AverageDataRate = 'aver', |
kICMCompressionSessionOptionsPropertyID_ColorTable = 'clut', |
kICMCompressionSessionOptionsPropertyID_CompressorComponent = 'imco', |
kICMCompressionSessionOptionsPropertyID_CompressorSettings = 'cost', |
kICMCompressionSessionOptionsPropertyID_CPUTimeBudget = 'cput', |
kICMCompressionSessionOptionsPropertyID_DataRateLimitCount = 'har#', |
kICMCompressionSessionOptionsPropertyID_DataRateLimits = 'hard', |
kICMCompressionSessionOptionsPropertyID_Depth = 'deep', |
kICMCompressionSessionOptionsPropertyID_DurationsNeeded = 'need', |
kICMCompressionSessionOptionsPropertyID_MaxDataRateLimits = 'mhar', |
kICMCompressionSessionOptionsPropertyID_MaxFrameDelayCount = 'cwin', |
kICMCompressionSessionOptionsPropertyID_MaxFrameDelayTime = 'cwit', |
kICMCompressionSessionOptionsPropertyID_MaxKeyFrameInterval = 'kyfr', |
kICMCompressionSessionOptionsPropertyID_MultiPassStorage = 'imps', |
kICMCompressionSessionOptionsPropertyID_Quality = 'qual', |
kICMCompressionSessionOptionsPropertyID_SourceFrameCount = 'frco', |
kICMCompressionSessionOptionsPropertyID_WasCompressed = 'wasc' |
kQTPropertyClass_ICMCompressionSessionOptions = 'icso'
Class identifier for compression session option object properties.
kICMCompressionSessionOptionsPropertyID_AllowAsyncCompletion = 'asok'
Enables the compressor to call the encoded-frame callback from a different thread. By default this option is
FALSE
, which means that the compressor must call the encoded-frame callback from the same thread asICMCompressionSessionEncodeFrame
andICMCompressionSessionCompleteFrames
.kICMCompressionSessionOptionsPropertyID_AllowFrameReordering = 'b ok'
Enables frame reordering. To encode B-frames a compressor must reorder frames, which may mean that the order in which they are emitted and stored (the decode order) may be different from the order in which they are presented to the compressor (the display order). By default, frame reordering is disabled. To encode using B-frames, you must enable frame reordering by passing
TRUE
in this property.kICMCompressionSessionOptionsPropertyID_AllowFrameTimeChanges = '+ ok'
Enables the compressor to modify frame times, improving its performance. Some compressors are able to identify and coalesce runs of identical frames and emit single frames with longer duration, or emit frames at a different frame rate from the original. By default, this flag is set to
FALSE
, which forces the compressor to emit one encoded frame for every source frame and to preserve frame display times. This option replaces the practice of having compressors return special high similarity values to indicate that frames can be dropped.kICMCompressionSessionOptionsPropertyID_AllowTemporalCompression = 'p ok'
Enables temporal compression of P-frames and B-frames. By default, temporal compression is disabled.
kICMCompressionSessionOptionsPropertyID_AverageDataRate = 'aver'
The long-term desired average data rate in bytes per second. This is not an absolute limit. The default data rate is zero, indicating that the setting of
kICMCompressionSessionOptionsPropertyID_Quality
should determine the size of compressed data. Data rate settings have effect only when timing information is provided for source frames. Some codecs do not accept limiting to specified data rates.kICMCompressionSessionOptionsPropertyID_ColorTable = 'clut'
The color table for compression, used with indexed-color depths. Clients who are passed this property are responsible for disposing the returned
CTabHandle
.kICMCompressionSessionOptionsPropertyID_CompressorComponent = 'imco'
Sets a specific compressor component or component instance to be used, or passes one of the wildcards
anyCodec
,bestSpeedCodec
,bestFidelityCodec
, orbestCompressionCodec
. Pass this option to force the Image Compression Manager to use a specific compressor component or compressor component instance. To allow the Image Compression Manager to choose the compressor component, set the compressorComponent toanyCodec
(the default),bestSpeedCodec
,bestFidelityCodec
, orbestCompressionCodec
. If you pass in a component instance that you opened, the ICM will not close that instance; you must do so after the compression session is released.kICMCompressionSessionOptionsPropertyID_CompressorSettings = 'cost'
A handle containing compressor settings. The compressor will be configured with these settings (by a call to
ImageCodecSetSettings
) during theICMCompressionSessionCreate
process.kICMCompressionSessionOptionsPropertyID_CPUTimeBudget = 'cput'
Recommends a CPU time budget for a compressor in microseconds per frame. Zero means to go as fast as possible. By default, this is set to
kICMUnlimitedCPUTimeBudget
, which sets no limit. This option provides only an advisory hint, and some compressors may ignore it. Compressors are not compelled to use the full time budget if they complete ahead of time. Multithreaded compressors may use this amount of CPU time on each processor.kICMCompressionSessionOptionsPropertyID_DataRateLimitCount = 'har#'
The current number of data rate limits.
kICMCompressionSessionOptionsPropertyID_DataRateLimits = 'hard'
Zero, one, or two hard limits on data rate. Each hard limit is described by a data size in bytes and a duration in seconds. It requires that the total size of compressed data for any contiguous segment of that duration (in decode time) must not exceed the data size. By default, no data rate limits are set. When setting this property, the inPropValueSize parameter should be the number of data rate limits multiplied by
sizeof(ICMDataRateLimit)
. Data rate settings have an effect only when timing information is provided for source frames. Some codecs do not accept limiting to specified data rates.kICMCompressionSessionOptionsPropertyID_Depth = 'deep'
The depth for compression. If a compressor does not support a specific depth, the closest supported depth will be used, preferring deeper depths to shallower depths. The default depth is
k24RGBPixelFormat
.kICMCompressionSessionOptionsPropertyID_DurationsNeeded = 'need'
Indicates that durations of emitted frames are needed. If this option is set and source frames are provided with times but not durations, then frames will be delayed so that durations can be calculated as the difference between one frame’s time stamp and the next frame’s time stamp. By default, this flag is
FALSE
, so frames will not be delayed in order to calculate durations. If you pass encoded frames toAddMediaSampleFromEncodedFrame
, you must set this flag toTRUE
.kICMCompressionSessionOptionsPropertyID_MaxDataRateLimits = 'mhar'
The maximum allowed number of data rate limits, currently 2.
kICMCompressionSessionOptionsPropertyID_MaxFrameDelayCount = 'cwin'
The maximum frame delay count is the maximum number of frames that a compressor is allowed to hold before it must output a compressed frame. This value limits the number of frames that may be held in the “compression window.” If the maximum frame delay count is M, then before the call to encode frame N returns, frame N-M must have been emitted. The default value is
kICMUnlimitedFrameDelayCount
, which sets no limit on the compression window.kICMCompressionSessionOptionsPropertyID_MaxFrameDelayTime = 'cwit'
The maximum frame delay time is the maximum difference between a source frame’s display time and the corresponding encoded frame»s decode time. This value limits the span of display time that may be held in the “compression window.” If the maximum frame delay time is TM, then before the call to encode a frame with display time TN returns, all frames with display times up to and including TN-TM must have been emitted. The default value is
kICMUnlimitedFrameDelayTime
, which sets no time limit on the compression window.kICMCompressionSessionOptionsPropertyID_MaxKeyFrameInterval = 'kyfr'
The maximum interval between key frames, also known as the key frame rate. Compressors are allowed to generate key frames more frequently if this would result in more efficient compression. The default key frame interval is 0, which indicates that the compressor should choose where to place all key frames. This differs from previous practice, in which a key frame rate of zero disabled temporal compression.
kICMCompressionSessionOptionsPropertyID_MultiPassStorage = 'imps'
A multipass compression client must provide a storage location for multipass data. Pass
ICMMultiPassStorageCreateWithTemporaryFile
to make the ICM store multipass data in a temporary file. PassICMMultiPassStorageCreateWithCallbacks
to manage the storage yourself. Note that the amount of multipass data to be stored can be substantial; it could be greater than the size of the output movie file. If this property is notNULL
, the client must callICMCompressionSessionBeginPass
andICMCompressionSessionEndPass
around groups of calls toICMCompressionSessionEncodeFrame
. By default, this property isNULL
and multipass compression is not enabled. The compression session options object retains the multipass storage object when one is set.kICMCompressionSessionOptionsPropertyID_Quality = 'qual'
The compression quality. This value is always used to set the spatial quality; if temporal compression is enabled, it is also used to set temporal quality. The default quality is
codecNormalQuality
.kICMCompressionSessionOptionsPropertyID_SourceFrameCount = 'frco'
Indicates the number of source frames, if known. If nonzero, this value should equal the exact number of times that the client calls
ICMCompressionSessionEncodeFrame
in each pass. The default is 0, which indicates that the number of source frames is not known.kICMCompressionSessionOptionsPropertyID_WasCompressed = 'wasc'
Indicates that the source was previously compressed. This property is an optional information hint to the compressor; by default it is
FALSE
.
ICM Compression Session Properties
The following constants represent properties of ICM compression sessions:
kQTPropertyClass_ICMCompressionSession = 'icse', |
kICMCompressionSessionPropertyID_CompressorPixelBufferAttributes = 'batt', |
kICMCompressionSessionPropertyID_ImageDescription = 'idsc', |
kICMCompressionSessionPropertyID_PixelBufferPool = 'pool', |
kICMCompressionSessionPropertyID_TimeScale = 'tscl' |
kQTPropertyClass_ICMCompressionSession = 'icse'
Class identifier for compression session properties.
kICMCompressionSessionPropertyID_CompressorPixelBufferAttributes = 'batt'
The compressor’s pixel buffer attributes for the compression session. You can use these to create a pixel buffer pool for source pixel buffers. This is not the same as the
sourcePixelBufferAttributes
property passed toICMCompressionSessionCreate
. Getting this property does not change its retain count.kICMCompressionSessionPropertyID_ImageDescription = 'idsc'
The image description for a compression session. For some codecs, the image description may not be available before the first frame is compressed. Multiple calls to retrieve this property will return the same handle. The ICM will dispose of this handle when the compression session is disposed; the caller must not dispose of it.
kICMCompressionSessionPropertyID_PixelBufferPool = 'pool'
A pool that can provide ideal source pixel buffers for a compression session. The compression session creates this pixel buffer pool based on the compressor’s pixel buffer attributes and any pixel buffer attributes passed in to
ICMCompressionSessionCreate
. If the source pixel buffer attributes and the compressor pixel buffer attributes can not be reconciled, the pool is based on the source pixel buffer attributes and the ICM converts eachCVPixelBuffer
internally.kICMCompressionSessionPropertyID_TimeScale = 'tscl'
The time scale for the compression session.
Movie Audio Mixes
Three new four-character constants define the mix of audio channels for several functions:
kQTAudioMeter_StereoMix = 'stmx' |
kQTAudioMeter_MonoMix = 'momx' |
kQTAudioMeter_DeviceMix = kQTAudioPropertyID_DeviceChannelLayout = 'dcly' |
kQTAudioMeter_StereoMix
Meter a stereo (two-channel) mix of the enabled sound tracks in the movie. This option is offered only for MovieAudioFrequencyMetering.
kQTAudioMeter_MonoMix
Meter the movie as if it had been mixed to monaural. This option is offered only for MovieAudioFrequencyMetering.
kQTAudioMeter_DeviceMix
Meter the movie’s mix to the
AudioChannelLayout
of the device the movie is playing to.
The constants listed above are passed by the following QuickTime 7 functions:
Audio Property Selectors
The following values are used as ComponentPropertyID
selectors.
Use these with the StandardCompressionSubTypeAudio ('scdi'/'audi'
)
component. All property IDs are to be used in conjunction with the kQTPropertyClass_SCAudio
property
class.
kQTSCAudioPropertyID_AvailableCompressionFormatList = 'acf#'
A read/listen C-style array of
OSType
values that specifies the list of available output compression formats. This list includes all thekAudioEncoderComponentType
components andkSoundCompressor
type components on the user’s system. You can restrict the list by using thekQTSCAudioPropertyID_CompressionFormatList
property. UseQTGetComponentPropertyInfo
to discover the number of bytes you should allocate for this array.kQTSCAudioPropertyID_ClientRestrictedCompressionFormatList = 'crf#'
A read/write/listen C-style array of
OSType
values that specifies a client-restricted set of output compression formats that you should list as available. UseQTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold this array.kQTSCAudioPropertyID_AvailableCompressionFormatNamesList = 'cnm#'
A read/write
CFArrayRef
structure ofCFStringRef
structures that reference the human-readable names of each item in akQTSCAudioPropertyID_AvailableCompressionFormatList
. The caller assumes responsibility for callingCFRelease
to dispose of theCFArrayRef
structure.kQTSCAudioPropertyID_HasLegacyCodecOptionsDialog = 'opn?'
Some compression formats have format-specific properties that are accessible only via a compressor-provided dialog. This constant specifies a read/listen
Boolean
value that lets you know if the current compression format has such a dialog.kQTSCAudioPropertyID_ConstantBitRateFormatsOnly = '!vbr'
By default, constant as well as variable bit rate compression formats are shown in the available format list. This constant specifies a read/write/listen
Boolean
value that lets you restrict the available formats to constant bit rate formats by setting this property toTRUE
.kQTSCAudioPropertyID_AvailableSampleRateList = 'avr#'
A read/listen C-style array of
AudioValueRange
values that specifies a list of available output sample rates. This list is specific to the compression format and takes into account any restrictions imposed by a client using thekQTSCAudioPropertyID_ClientRestrictedSampleRateList
property. UseQTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold this array.kQTSCAudioPropertyID_SampleRateRecommended = 'reco'
Clients not wishing to set an output sample rate manually may set the output rate to the recommended rate. Some compressors can perform rate conversion, and can pick optimal settings for a desired bitrate (AAC is one example). For other formats, the recommended rate is simply the closest output rate to the input rate that's allowed by the output format.
kQTSCAudioPropertyID_SampleRateIsRecommended
is read-only. To set the sample rate to recommended, a client sets thekQTSCAudioPropertyID_BasicDescription
withmSampleRate
= 0.0. To unset the sample rate as recommended, the client sets thekQTSCAudioPropertyID_BasicDescription
with a non-zeromSampleRate
field.kQTSCAudioPropertyID_ApplicableSampleRateList = 'avr#'
A read/listen C-style array of
AudioValueRange
values that specifies which of the value ranges in thekQTSCAudioPropertyID_AvailableSampleRateList
are currently applicable. ThekQTSCAudioPropertyID_AvailableSampleRateList
takes into account client restrictions, and a compression format's general sample rate restrictions.kQTSCAudioPropertyID_ApplicableSampleRateList
further filters the list to just those sample rates that are legal and valid given the current codec configuration. UseQTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold the array.kQTSCAudioPropertyID_ClientRestrictedSampleRateList = 'crr#'
A read/write/listen C-style array of
AudioValueRange
values that specifies a client-restricted set of output sample rate ranges that should be listed as available. UseQTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold this array.kQTSCAudioPropertyID_InputMagicCookie = 'ikki'
A read/write/listen opaque data structure that contains an untyped codec-specific data structure (a “magic cookie”), which some decompressors use to decode their input. Cookies are variable size, so you must call
QTGetComponentPropertyInfo
to discover the size of the buffer you should allocate to hold the cookie.kQTSCAudioPropertyID_MagicCookie = 'kuki'
A read/write/listen opaque data structure that contains an untyped codec-specific data structure (a “magic cookie”), which some decompressors use to configure their output. Cookies are variable size, so you must call
QTGetComponentPropertyInfo
to discover the size of the buffer you should allocate to hold the cookie.kQTSCAudioPropertyID_ClientRestrictedLPCMBitsPerChannelList = 'crb#'
Specifies a client-restricted set of output bits per channel that should be listed as available. Use
QTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold the array.kQTSCAudioPropertyID_AvailableLPCMBitsPerChannelList = 'avb#'
A read/listen C-style array of
UInt32
values that contains a list of available bits per audio channel. This list is specific to LPCM, and takes into account any restrictions imposed by a client using thekQTSCAudioPropertyID_LPCMBitsPerChannelList
property. UseQTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold this array.kQTSCAudioPropertyID_ApplicableLPCMBitsPerChannelList = 'apb#'
Specifies which of the values in the
kQTSCAudioPropertyID_AvailableLPCMBitsPerChannelList
are currently applicable. ThekQTSCAudioPropertyID_AvailableLPCMBitsPerChannelList
takes into account client restrictions, and LPCM’s general bits per channel restrictions.kQTSCAudioPropertyID_ApplicableLPCMBitsPerChannelList
further filters the list to just those bits per channel that are legal and valid given the current LPCM configuration. UseQTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold the array.kQTSCAudioPropertyID_LPCMBitsPerChannelList = 'sbc#'
A read/write/listen C-style array of
UInt32
values that contains a client-restricted set of output bits per channel, which you should list as available. UseQTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold this array.kQTSCAudioPropertyID_AvailableNumChannelsList = 'anc#'
A read/listen C-style array of
UInt32
values that contains a list of available numbers of channels. This list is specific to the compression format and takes into account any restrictions imposed by a client using thekQTSCAudioPropertyID_NumChannelsList
property. UseQTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold this array.kQTSCAudioPropertyID_NumChannelsList = 'snc#'
A read/write/listen C-style array of
UInt32
values that contains a client-restricted set of numbers of channels that you should list as available. UseQTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold this array.kQTSCAudioPropertyID_InputChannelLayout = 'icly'
A read/write/listen variable-size
AudioChannelLayout
structure that specifies the audio channel layout of the input description.AudioChannelLayout
is a variable-size structure, so you must useQTGetComponentPropertyInfo
to discover the number of bytes you should allocate for it.kQTSCAudioPropertyID_InputChannelLayoutName = 'icln'
A read-only
CFStringRef
structure that specifies the human-readable name for akQTSCAudioPropertyID_InputChannelLayout
structure, if one exists. The caller is responsible for callingCFRelease
to dispose of the resulting string.kQTSCAudioPropertyID_ChannelLayout = 'clay'
A read/write/listen variable-size
AudioChannelLayout
structure that specifies the audio channel layout of the output description.AudioChannelLayout
is a variable size structure, so you must useQTGetComponentPropertyInfo
to discover the number of bytes you should allocate.kQTSCAudioPropertyID_ChannelLayoutName = 'clyn'
A read-only
CFStringRef
structure that specifies the human-readable name for akQTSCAudioPropertyID_ChannelLayout
, if one exists. The caller is responsible for callingCFRelease
to dispose of the resulting string.kQTSCAudioPropertyID_ClientRestrictedChannelLayoutTagList = 'crl#'
Specifies a client-restricted set of channel layout tags that should be listed as available. Use
QTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold the array.kQTSCAudioPropertyID_AvailableChannelLayoutTagList = 'acl#'
A read/listen C-style array of
AudioChannelLayoutTag
values that specifies a list of available audio channel layout tags. This list is specific to the compression format and takes into account any restrictions imposed by a client using thekQTSCAudioPropertyID_ChannelLayoutTagList
property. UseQTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold this array.kQTSCAudioPropertyID_ChannelLayoutTagList = 'cly#'
A read/write C-style array of
AudioChannelLayoutTag
values that specifies a client-restricted set of channel layout tags, which you should list as available. UseQTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold this array.kQTSCAudioPropertyID_AvailableChannelLayoutTagNamesList = 'cln#'
A read-only
CFArrayRef
array that specifies the human-readable names for theAudioChannelLayoutTag
values in akQTSCAudioPropertyID_AvailableChannelLayoutTagList
. Each element in the array is aCFStringRef
structure. The caller is responsible for callingCFRelease
to dispose of this array.kQTSCAudioPropertyID_ApplicableChannelLayoutTagNamesList = 'apl#'
Specifies which of the values in the
kQTSCAudioPropertyID_AvailableChannelLayoutTagList
are currently applicable. ThekQTSCAudioPropertyID_AvailableChannelLayoutTagList
takes into account client restrictions, and the current output format’s general channel layout restrictions.kQTSCAudioPropertyID_ApplicableChannelLayoutTagList
further filters the list to just those channel layouts that are legal and valid given the current codec configuration. UseQTGetComponentPropertyInfo
to discover the number of bytes you should allocate to hold the array.kQTSCAudioPropertyID_ClientRestrictedPCMFlags = 'crip'
Specifies a client-restricted set of flags corresponding to the
mFormatFlags
fields in anAudioStreamBasicDescription
. Data type is aSCAudioFormatFlagsRestrictions
struct. For instance, if a client wishes to specify to the StandardAudioCompression component that their file format requires little endian pcm data, the client may set this property, withformatFlagsMask
set tokAudioFormatFlagIsBigEndian
, andformatFlagsValues
set to zero (indicating that the IsBigEndian bit should be interpreted as LittleEndian only).kQTSCAudioPropertyID_DiscreteChannelsOK = 'dscr'
A read/write/listen
Boolean
value that lets you tell theStandardCompressionSubTypeAudio
dialog to not show “Discrete” as an available option. EachAudioChannelLayout
structure assigns specific spatial orientation to specific channels (for example, Channel 1 = Left). “Discrete” is a special channel layout that does not assign spatial characteristics to channels, but instead labels them as distinct outputs. For example, the first channel in the audio source is played through the first channel on the output device, the second channel in the source is played through the second channel, and so on. If this property is set toFALSE
, theStandardCompressionSubTypeAudio
dialog will not show “Discrete” as an available option.kQTSCAudioPropertyID_LPCMSpecificFlagsMask = 'sffm'
A read/write/listen
UInt32
value that specifies which flag fields inkQTSCAudioPropertyID_FormatSpecificFlags
should be made available in theStandardCompressionSubTypeAudio
dialog. For instance, a value of0xFFFFFFFD
(all bits exceptkAudioFormatFlagIsBigEndian
set) tells theStandardCompressionSubTypeAudio
component to disable any UI that would allow a choice between little and big endian. This selector is valid only for PCM formats and is ignored for others.kQTSCAudioPropertyID_InputSoundDescription = 'isdh'
A read/write
SoundDescriptionHandle
value that specifies the current input description as aSoundDescriptionHandle
(lowest possible version for the current format). When callingQTGetComponentProperty
, the caller passes a pointer to an unallocatedHandle
and assumes responsibility for callingDisposeHandle
when done.kQTSCAudioPropertyID_SoundDescription = 'osdh'
A read/write
SoundDescriptionHandle
value that specifies the current output description as aSoundDescriptionHandle
(lowest possible version for the current format). When callingQTGetComponentProperty
, the caller passes a pointer to an unallocatedHandle
and assumes responsibility for callingDisposeHandle
when done.kQTSCAudioPropertyID_InputBasicDescription = 'isbd'
A read/write/
DataProc
/listenAudioStreamBasicDescription
value that specifies that the current input description is anAudioStreamBasicDescription
value.kQTSCAudioPropertyID_BasicDescription = 'osbd'
A read/write/
DataProc
/listenAudioStreamBasicDescription
value that specifies that the current output description is anAudioStreamBasicDescription
value.kQTSCAudioPropertyID_CodecSpecificSettingsArray = 'cdst'
A read/write
CFArrayRef
structure that designates aCFArray
ofCFDictionary
structures, which describe various parameters specific to configuring a codec. This array of dictionaries, which is published by some compressors, can be parsed to generate UI information. When any value in the array changes, a client should callQTSetComponentProperty
, passing the entire array.kQTSCAudioPropertyID_SettingsState = scSettingsStateType
A read/write
Handle
value that is used to save the current state of theStandardCompressionSubTypeAudio
component, so that its state may be restored at a later time with a single call. AStandardCompressionSubTypeAudio
component can accept a saved settings state from a legacyStandardCompressionSubTypeSound
component as write-only.kQTSCAudioPropertyID_ExtendedProcs = scExtendedProcsType
A read/write/listen
SCExtendedProcs
value that is used to get or set anSCExtendedProcs
structure.kQTSCAudioPropertyID_PreferenceFlags = scPreferenceFlagsType
A read/write/listen
SInt32
value that is used to specify dialog preferences such asscUseMovableModal
.kQTSCAudioPropertyID_WindowOptions = scWindowOptionsType
A read/write/listen
SCWindowSettings
structure that is used to set anSCWindowSettings
structure, which tells the dialog about its parent window so that it can draw itself as a sheet on top of the parent.
Movie Exporter Properties
The following constants are used by movie export getProperty
functions
only (not SCAudio
), so that variable
size properties can be handled in that API where there is no associated
size parameter. The getProperty
function
can be asked the size first, then the caller can allocate memory
for the associated SCAudio
property
and call getProperty
again to get the
property.
enum { |
movieExportChannelLayoutSize = 'clsz', /* UInt32 */ |
movieExportMagicCookieSize = 'mcsz', /* UInt32 */ |
movieExportUseHighResolutionAudioProperties = 'hrau' /* Boolean */ |
}; |
The movieExportUseHighResolutionAudioProperties
constant
is not a size. It is how the exporter asks a propertyProc if it
is prepared to deal with high-res properties.
The kPropertyClass_MovieExporter
constant
defines the movie exporter class:
enum { |
kPropertyClass_MovieExporter = 'spit' |
}; |
The kMovieExporterPropertyID_EnableHighResolutionAudioFeatures
constant
enables high-resolution audio features for kPropertyClass_MovieExporter
.
Its value is Boolean
:
enum { |
kMovieExporterPropertyID_EnableHighResolutionAudioFeatures = 'hrau' |
}; |
Audio Property IDs
The following constants identify audio properties.
enum { |
kQTAudioPropertyID_Gain = 'gain', |
kQTAudioPropertyID_Mute = 'mute', |
kQTAudioPropertyID_Balance = 'bala', |
kQTAudioPropertyID_SummaryChannelLayout = 'clay', |
kQTAudioPropertyID_DeviceChannelLayout = 'dcly', |
kQTAudioPropertyID_FormatString = 'fstr', |
kQTAudioPropertyID_ChannelLayoutString = 'lstr', |
kQTAudioPropertyID_SampleRateString = 'rstr', |
kQTAudioPropertyID_SampleSizeString = 'sstr', |
kQTAudioPropertyID_BitRateString = 'bstr', |
kQTAudioPropertyID_SummaryString = 'asum' |
}; |
kQTAudioPropertyID_Gain = 'gain'
Used to get and set a
Float32
value that represents the audio gain of a movie or track. The gain level is multiplicative; eg. 0.0 is silent, 0.5 is –6dB, 1.0 is 0dB (ie. the audio from the movie is not modified), 2.0 is +6dB, etc. The gain level can be set higher than 1.0 in order to allow quiet movies and tracks to be boosted in volume. Settings higher than 1.0 may result in audio clipping, of course. The setting is not stored in the movie or track; it is used only until the movie or track is disposed.kQTAudioPropertyID_Mute = 'mute'
Used to get and set a
Boolean
value that indicates the audio mute state of a movie or track. If TRUE, the movie or track is muted. The setting is not stored in the movie or track; it is used only until the movie or track is disposed.kQTAudioPropertyID_Balance = 'bala'
Used to get and set a
Float32
value that represents the audio balance of a movie. It is supported only for movies, not tracks. –1.0 means full left, 0.0 means centered, and 1.0 means full right. The setting is not stored in the movie; it is used only until the movie is disposed.kQTAudioPropertyID_SummaryChannelLayout = 'clay'
Used to get an
AudioChannelLayout
value that represents the summary audio channel layout of a movie or other grouping of audio streams. All like-labelled channels are combined, so there are no duplicates. For example, if there is a stereo (L/R) track, 5 single-channel tracks marked Left, Right, Left Surround, Right Surround and Center, and a 4 channel track marked L/R/Ls/Rs, then the summary AudioChannelLayout will be L/R/Ls/Rs/C—It will _not_ be L/R/L/R/Ls/Rs/C/L/R/Ls/Rs. This is a variable-size property, because it it may contain an array of channel descriptions. You must get the size by calling a function such asQTGetMoviePropertyInfo
, allocate a structure of that size, and then get the property.kQTAudioPropertyID_DeviceChannelLayout = 'dcly'
Used to get an
AudioChannelLayout
value that represents the audio channel layout of the device a movie is playing to. This is a variable-size property, because it it may contain an array of channel descriptions. You must get the size by calling a function such asQTGetMoviePropertyInfo
, allocate a structure of that size, and then get the property.kQTAudioPropertyID_FormatString = 'fstr'
Used with
kQTPropertyClass_Audio
to get aCFStringRef
value containing a localized, human readable string that describes an audio format; for example, “MPEG Layer 3.” You may get this property from aSoundDescription
handle by callingQTSoundDescriptionGetProperty
or from aStandardAudioCompression
(scdi
oraudi
) component instance by callingQTGetComponentProperty
.kQTAudioPropertyID_ChannelLayoutString = 'lstr'
Used with
kQTPropertyClass_Audio
to get aCFStringRef
value containing a localized, human readable string that describes an audio channel layout; for example, “5.0 (L R C Ls Rs).” You may get this property from aSoundDescription
handle by callingQTSoundDescriptionGetProperty
or from aStandardAudioCompression
(scdi
oraudi
) component instance by callingQTGetComponentProperty
.kQTAudioPropertyID_SampleRateString = 'rstr'
Used to get a
CFStringRef
value containing a localized, human readable string that describes an audio sample rate; for example, “44.100 kHz.” You may get this property from aSoundDescription
handle by callingQTSoundDescriptionGetProperty
or from aStandardAudioCompression
(scdi
oraudi
) component instance by callingQTGetComponentProperty
.kQTAudioPropertyID_SampleSizeString = 'sstr'
Used to get a
CFStringRef
value containing a localized, human readable string that describes an audio sample size; for example, “24-bit.” This property will return a valid string only if the audio format is uncompressed (LPCM). You may get this property from aSoundDescription
handle by callingQTSoundDescriptionGetProperty
or from aStandardAudioCompression
(scdi
oraudi
) component instance by callingQTGetComponentProperty
.kQTAudioPropertyID_BitRateString = 'bstr'
Used to get a
CFStringRef
value containing a localized, human readable string that describes an audio bit rate; for example, “12 kbps.” You may get this property from aStandardAudioCompression
(scdi
oraudi
) component instance by callingQTGetComponentProperty
.kQTAudioPropertyID_SummaryString = 'asum'
Used to get a
CFStringRef
value containing a localized, human readable string that summarizes an audio format; for example, “16-bit Integer (Big Endian), Stereo (L R), 48.000 kHz.” You may get this property from aSoundDescription
handle by callingQTSoundDescriptionGetProperty
or from aStandardAudioCompression
(scdi
oraudi
) component instance by callingQTGetComponentProperty
.
Dictionary Keys
The dictionary keys listed in this section
are used with c ertain of the property IDs. They may be used to
parse CF dictionaries returned by kQTSGAudioPropertyID_DeviceListWithAttributes
and kQTSGAudioPropertyID_DeviceAttributes
IDs
for SGAudioMediaType
channels.
kQTAudioDeviceAttribute_DeviceUIDKey = 'uid '
A
CFStringRef
containing a unique identifier for a device.kQTAudioDeviceAttribute_DeviceNameKey = 'name'
A
CFStringRef
containing a device’s printable name, suitable for the user interface.kQTAudioDeviceAttribute_DeviceManufacturerKey = 'manu'
A
CFStringRef
containing a device manufacturer’s printable name, suitable for the user interface.kQTAudioDeviceAttribute_DeviceTransportTypeKey = 'tran'
A
CFNumberRef
that wraps anOSType
; for example,'1394'
forfw
. See the fileIOAudioTypes.h
.kQTAudioDeviceAttribute_DeviceAliveKey = 'aliv'
A
CFBooleanRef
value that isTRUE
if the device is present.kQTAudioDeviceAttribute_DeviceCanRecordKey = 'rec ' [last char = space]
A
CFBooleanRef
value that isTRUE
if the device can be used for recording (some devices can only play back).kQTAudioDeviceAttribute_DeviceCanPreviewKey = 'prev'
A
CFBooleanRef
value that isTRUE
if the device can be used to preview a grabbed sequence.kQTAudioDeviceAttribute_DeviceHoggedKey = 'hogg'
A
CFNumberRef
that wraps the unique process ID that is hogging the device, or –1 if the device is currently not being hogged. The process ID comes from a call togetpid
.kQTAudioDeviceAttribute_DeviceInUseKey = 'used'
A
CFBooleanRef
value that isTRUE
if the device is performing I/O in any process.kQTAudioDeviceAttribute_DeviceSupportsHardwarePlaythruKey = 'hard'
A
CFBooleanRef
value that isTRUE
if the device supports hardware playthrough of inputs to outputs.kQTAudioDeviceAttribute_DefaultInputDeviceKey = 'dIn ' [last char = space]
A
CFBooleanRef
value that’sTRUE
if the device is the user-selected default input in an audio MIDI setup.kQTAudioDeviceAttribute_DefaultOutputDeviceKey = 'dOut'
A
CFBooleanRef
value that’sTRUE
if the device is the user-selected default output in an audio MIDI setup.kQTAudioDeviceAttribute_DefaultSystemOutputDeviceKey = 'sOut'
A
CFBooleanRef
value that’sTRUE
if the device is the user-selected device where system alerts play.kQTAudioDeviceAttribute_IsCoreAudioDeviceKey = 'hal!'
A
CFBooleanRef
value that’sTRUE
if the device is a Core Audio device.
Device Attribute Keys for Inputs and Outputs
The following dictionary keys may be used
to parse CF dictionaries returned by kQTSGAudioPropertyID_DeviceListWithAttributes
and kQTSGAudioPropertyID_DeviceAttributes
IDs
for SGAudioMediaType
channels.
kQTAudioDeviceAttribute_DeviceInputID = 'inID'
A
CFNumberRef
that wraps anOSType
value.kQTAudioDeviceAttribute_DeviceInputDescription = 'inds'
A
CFStringRef
that is suitable for displaying to the user.kQTAudioDeviceAttribute_DeviceOutputID = 'otID'
A
CFNumberRef
that wraps anOSType
value.kQTAudioDeviceAttribute_DeviceOutputDescription = 'otds'
A
CFStringRef
that is suitable for displaying to the user.
Metadata Format Constants
The format constants in this section are
used with functions of the form QTMetaData
...
Following are constants for the QTMetaDataStorageFormat
type:
kQTMetaDataStorageFormatQuickTime = 'mdta'
The QuickTime metadata storage format
kQTMetaDataKeyFormatQuickTime = 'mdta'
Reverse DNS format
kQTMetaDataStorageFormatiTunes = 'itms'
The iTunes metadata storage format
Following are constants for the QTMetaDataKeyFormat
type:
kQTMetaDataKeyFormatiTunesShortForm = 'itsk'
A four-character code
kQTMetaDataKeyFormatiTunesLongForm = 'itlk'
Reverse DNS format
Following are constants for user data formats:
kQTMetaDataStorageFormatUserData = 'udta'
User data storage format
kQTMetaDataKeyFormatUserData = 'udta',
User data key storage format
Metadata Property IDs
The property IDs in this section are used
with functions of the form QTMetaData
...
Following are constants for the QTMetaDataRef
type:
kPropertyClass_QTMetaData = 'meta'
The QuickTime metadata property class.
kQTMetaDataPropertyID_StorageFormats = 'fmts'
The list of storage formats of type
QTMetaDataStorageFormat
associated with aQTMetaDataRef
object. The read-only return value is a C-style array ofOSType
values.kQTMetaDataPropertyID_OwnerType = 'ownt'
The owner type associated with a
QTMetaDataRef
object. The read-only return value is anOSType
(QT_MOVIE_TYPE
,QT_TRACK_TYPE
, orQT_MEDIA_TYPE
).kQTMetaDataPropertyID_Owner = 'ownr'
The owner associated with a
QTMetaDataRef
object, which does not necessarily need an owner. The read-only return value is typeMovie
,Track
, orMedia
.
Following are constants for the QTMetaDataItem
type:
kPropertyClass_QTMetaDataItem = 'mdit'
The metadata item property class ID
kQTMetaDataItemPropertyID_Value = 'valu'
The value of the metadata item. The read-only return value is a C-style array of values of type
UInt8
.kQTMetaDataItemPropertyID_DataType = 'dtyp'
The value type of the metadata item. The read/write return value is type
UInt32
.kQTMetaDataItemPropertyID_StorageFormat = 'sfmt'
The storage format of the metadata item. The read-only return value is type
QTMetaDataStorageFormat
.kQTMetaDataItemPropertyID_Key = 'key '
[last char is space]The key associated with the metadata item. The read/write return value is a C-style array of values of type
UInt8
.kQTMetaDataItemPropertyID_KeyFormat = 'keyf'
The format of the metadata item key. The read/write return value is type
OSType
.kQTMetaDataItemPropertyID_Locale = 'loc '
The locale identifier based on the naming convention defined by the International Components for Unicode (ICU). The identifier consists of two pieces of ordered information: a language code and a region code. The language code is based on the ISO 639-1 standard, which defines two-character codes, such as
en
andfr
, for the world’s most commonly used languages. If a two-letter code is not available, then ISO 639-2 three-letter identifiers are accepted as well; for example,haw
for Hawaiian. The region code is defined by ISO 3166-1. It is all uppercase and is appended, with an underscore, after the language code; for exampleen_US
,en_GB
, andfr_FR
. The read/write return value is a C string of typeUInt32
.
Metadata Key Constants
The following key constants are used with
functions of the form QTMetaData
...
// Pre-defined common keys |
kQTMetaDataCommonKeyAuthor = 'auth' |
kQTMetaDataCommonKeyComment = 'cmmt' |
kQTMetaDataCommonKeyCopyright = 'cprt' |
kQTMetaDataCommonKeyDirector = 'dtor' |
kQTMetaDataCommonKeyDisplayName = 'name' |
kQTMetaDataCommonKeyInformation = 'info' |
kQTMetaDataCommonKeyKeywords = 'keyw' |
kQTMetaDataCommonKeyProducer = 'prod' |
// Mapping from common keys to user data identifiers: |
kQTMetaDataCommonKeyAuthor -> kUserDataTextAuthor |
kQTMetaDataCommonKeyComment -> kUserDataTextComment |
kQTMetaDataCommonKeyCopyright -> kUserDataTextCopyright |
kQTMetaDataCommonKeyDirector -> kUserDataTextDirector |
kQTMetaDataCommonKeyDisplayName -> kUserDataTextFullName |
kQTMetaDataCommonKeyInformation -> kUserDataTextInformation |
kQTMetaDataCommonKeyKeywords -> kUserDataTextKeywords |
kQTMetaDataCommonKeyProducer -> kUserDataTextProducer |
Metadata Error Codes
The following error codes are returned by
functions of the form QTMetaData
...
kQTMetaDataInvalidMetaDataErr = -2173 |
kQTMetaDataInvalidItemErr = -2174 |
kQTMetaDataInvalidStorageFormatErr = -2175 |
kQTMetaDataInvalidKeyFormatErr = -2176 |
kQTMetaDataNoMoreItemsErr = -2177 |
New Movie Property Codes
The following codes are stored in the propClass fields
of QTNewMoviePropertyElement
data
structures, which pass them to NewMovieFromProperties
.
kQTPropertyClass_DataLocation = 'dloc', |
kQTDataLocationPropertyID_DataReference = 'dref', |
// DataReferenceRecord * |
kQTDataLocationPropertyID_CFStringNativePath = 'cfnp', |
// CFStringRef * |
kQTDataLocationPropertyID_CFStringPosixPath = 'cfpp', |
// CFStringRef * |
kQTDataLocationPropertyID_CFStringHFSPath = 'cfhp', |
// CFStringRef * |
kQTDataLocationPropertyID_CFStringWindowsPath = 'cfwp', |
// CFStringRef * |
kQTDataLocationPropertyID_CFURL = 'cfur', |
// CFURLRef * |
kQTDataLocationPropertyID_QTDataHandler = 'qtdh', |
// DataHandler * |
kQTDataLocationPropertyID_Scrap = 'scrp', |
// NULL |
kQTDataLocationPropertyID_LegacyMovieResourceHandle = 'rezh', |
// Handle * |
kQTDataLocationPropertyID_MovieUserProc = 'uspr', |
// QTNewMovieUserProcRecord * |
kQTDataLocationPropertyID_ResourceFork = 'rfrk', |
// SInt16 * |
kQTDataLocationPropertyID_DataFork = 'dfrk', |
// SInt16 * |
kQTPropertyClass_Audio = 'audi', |
kQTAudioPropertyID_RateChangesPreservePitch = 'aucp', // Boolean * |
kQTPropertyClass_Context = 'ctxt', |
kQTContextPropertyID_AudioContext = 'audi', |
// QTAudioContextRef * |
kQTContextPropertyID_VisualContext = 'visu', |
// QTVisualContextRef * |
kQTPropertyClass_MovieResourceLocator = 'rloc', |
kQTMovieResourceLocatorPropertyID_LegacyResID = 'rezi', |
// SInt16 * (input/output property) |
kQTMovieResourceLocatorPropertyID_LegacyResName = 'rezn', |
// Str255 (output property) |
kQTMovieResourceLocatorPropertyID_FileOffset = 'foff', |
// UInt64 * |
kQTMovieResourceLocatorPropertyID_Callback = 'calb', |
// User-defined |
kQTPropertyClass_MovieInstantiation = 'mins', |
kQTMovieInstantiationPropertyID_DontResolveDataRefs = 'rdrn', |
// Boolean * |
kQTMovieInstantiationPropertyID_DontAskUnresolvedDataRefs = 'aurn', |
// Boolean * |
kQTMovieInstantiationPropertyID_DontAutoAlternates = 'aaln', |
// Boolean * |
kQTMovieInstantiationPropertyID_DontUpdateForeBackPointers = 'fbpn', |
// Boolean * |
kQTMovieInstantiationPropertyID_AsyncOK = 'asok', |
// Boolean * |
kQTMovieInstantiationPropertyID_IdleImportOK = 'imok', |
// Boolean * |
kQTMovieInstantiationPropertyID_DontAutoUpdateClock = 'aucl', |
// Boolean * |
kQTMovieInstantiationPropertyID_ResultDataLocationChanged = 'dlch', |
// Boolean * (output property) |
kQTPropertyClass_NewMovieProperty = 'mprp', |
kQTNewMoviePropertyID_DefaultDataRef = 'ddrf', |
// DataReferenceRecord * |
kQTNewMoviePropertyID_Active = 'actv', |
// Boolean * |
kQTNewMoviePropertyID_DontInteractWithUser = 'intn', |
// Boolean * |
Copyright © 2005 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2005-11-09