ADC Home > Reference Library > Release Notes > QuickTime > QuickTime 7.1 Update Reference >

Functions

Functions by Task

Visual Context APIs for Windows

Aperture Mode APIs

Audio API For Windows

Functions

GenerateMovieApertureModeDimensions

Examines a movie and sets up track aperture mode dimensions.

OSErr GenerateMovieApertureModeDimensions (
   Movie movie
);

Parameters
movie

The movie.

Discussion

This function can be used to add information needed to support aperture modes to tracks created with applications and/or versions of QuickTime that did not support aperture mode dimensions. If the image descriptions in video tracks lack tags describing clean aperture and pixel aspect ratio information, the media data may be scanned to see if the correct values can be determined and attached. Then the aperture mode dimensions are calculated and set. Afterwards, the kQTVisualPropertyID_HasApertureModeDimensions property will be set to TRUE for these tracks. Tracks that do not support aperture modes are not changed.

Version Notes

Introduced in QuickTime 7.1.

Availability
Declared In
Movies.h

GenerateTrackApertureModeDimensions

Examines a track and sets up aperture mode dimensions.

OSErr GenerateTrackApertureModeDimensions (
   Track track
);

Parameters
track

The track.

Discussion

This function can be used to add information needed to support aperture modes to tracks created with applications and/or versions of QuickTime that did not support aperture mode dimensions. If the image descriptions in video tracks lack tags describing clean aperture and pixel aspect ratio information, the media data may be scanned to see if the correct values can be determined and attached. Then the aperture mode dimensions are calculated and set. Afterwards, the kQTVisualPropertyID_HasApertureModeDimensions property will be set to TRUE for these tracks. Tracks that do not support aperture modes are not changed.

Version Notes

Introduced in QuickTime 7.1.

Availability
Declared In
Movies.h

GetMovieVisualContext

Returns the current visual context for a movie.

OSStatus GetMovieVisualContext (
   Movie movie,
   QTVisualContextRef *visualContext
);

Parameters
movie

The movie.

visualContext

A pointer to a variable to receive the visual context.

Return Value

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

Discussion

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

Version Notes

Introduced in QuickTime 7 for Mac OS X and in QuickTime 7.1 for Windows.

Availability
Declared In
Movies.h

ICMDecompressionSessionCreateForVisualContext

Creates a session for decompressing video frames.

OSStatus ICMDecompressionSessionCreateForVisualContext (
   CFAllocatorRef allocator,
   ImageDescriptionHandle desc,
   ICMDecompressionSessionOptionsRef decompressionOptions,
   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 for Mac OS X and in QuickTime 7.1 for Windows.

Availability
Related Sample Code
Declared In
ImageCompression.h

MediaGenerateApertureModeDimensions

Examines media and sets up track aperture mode dimensions.

ComponentResult MediaGenerateApertureModeDimensions (
   MediaHandler mh
);

Parameters
mh

The media handler.

Discussion

If the sample descriptions tracks lack tags describing clean aperture and pixel aspect ratio information, the media data may be scanned to see if the correct values can be determined and attached. Then the aperture mode dimensions should be calculated and set by MediaSetTrackApertureModeDimensionsUsingSampleDescription.

Version Notes

Introduced in QuickTime 7.1

Availability
Declared In
MediaHandlers.h

MediaGetApertureModeClipRectForSampleDescriptionIndex

Calculates a source clip rectangle appropriate for the current aperture mode and the given sample description.

ComponentResult MediaGetApertureModeClipRectForSampleDescriptionIndex (
   MediaHandler mh,
   long sampleDescIndex,
   FixedRect *clipFixedRectOut
);

Parameters
mh

The media handler.

sampleDescIndex

Indicates the sample description index of sample description in the media.

clipFixedRectOut

Points to a variable to receive the clip rectangle.

Discussion

If the track’s aperture mode is kQTApertureMode_CleanAperture, the rectangle should be the clean aperture as described by the sample description (see kICMImageDescriptionPropertyID_CleanApertureClipRect); otherwise, it should be the full dimensions of the sample description.

Version Notes

Introduced in QuickTime 7.1.

Availability
Declared In
MediaHandlers.h

MediaGetApertureModeMatrixForSampleDescriptionIndex

Calculates a matrix appropriate for the current aperture mode and the given sample description.

ComponentResult MediaGetApertureModeMatrixForSampleDescriptionIndex (
   MediaHandler mh,
   long sampleDescIndex,
   MatrixRecord *matrixOut
);

Parameters
mh

The media handler.

sampleDescIndex

Indicates the sample description index of sample description in the media.

matrixOut

Points to a variable to receive the matrix.

Discussion

If the track’s aperture mode is kQTApertureMode_CleanAperture or kQTApertureMode_ProductionAperture, the matrix should scale horizontally to compensate for the pixel aspect ratio. Otherwise, the matrix should be identity. If the track’s aperture mode is kQTApertureMode_CleanAperture, the matrix should translate the top-left point of the clean aperture to the origin. (See kICMImageDescriptionPropertyID_CleanApertureMatrix and kICMImageDescriptionPropertyID_ProductionApertureMatrix).

Version Notes

Introduced in QuickTime 7.1.

Availability
Declared In
MediaHandlers.h

MediaSetTrackApertureModeDimensionsUsingSampleDescription

Sets the three aperture mode dimension properties on the track, calculating the values using the provided sample description.

ComponentResult MediaSetTrackApertureModeDimensionsUsingSampleDescription (
   MediaHandler mh,
   SampleDescriptionHandle sampleDesc
);

Parameters
mh

The media handler.

sampleDesc

The sample description handle.

Discussion

Use this function to calculate the values of the three aperture mode dimension properties on the track, using the provided sample description

Version Notes

Introduced in QuickTime 7.1.

Availability
Declared In
MediaHandlers.h

QTDirect3DTextureContextCreate

Creates a Direct3D texture context for a specified Direct3D context and pixel format. 

OSErr QTDirect3DTextureContextCreate (
   CFAllocatorRef               allocator,
   void*                        d3dDevice, // LPDIRECT3DDEVICE9
   UInt32                       d3dPixelFormat,
   CFDictionaryRef              attributes,
   QTVisualContextRef           *newTextureContext );

Parameters
allocator

An allocator used to create the texture context.

d3dDevice

A Direct3D device used to create textures.

d3dPixelFormat

The Direct3D pixel format used to create the Direct3D device.

attributes

A dictionary of attributes.

newTextureContext

A pointer to a variable to receive the new Direct3D texture context.

Return Value

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

kQTVisualContextNotAllowedErr if the graphics hardware is not supported.

memFullErr if there is insufficient memory to allocate the visual context.

Discussion

This routine lets you create a visual context you can draw into, if given a Direct3D device. The routine works similar to QTOpenGLTextureContextCreate in QuickTime 7 for Mac OS X.

Version Notes

Introduced in QuickTime 7 for Mac OS X and in QuickTime 7.1 for Windows.

Availability
Declared In
ImageCompression.h

QTVisualContextCopyImageForTime

Retrieves an image buffer from the visual context, indexed by the provided time.

OSStatus QTVisualContextCopyImageForTime (
   QTVisualContextRef visualContext,
   CFAllocatorRef allocator,
   const CVTimeStamp *timeStamp,
   CVImageBufferRef *newImage
);

Parameters
visualContext

The visual context.

allocator

Allocator used to create new CVImageBufferRef.

timeStamp

Time in question. Pass NULL to request the image at the current time.

newImage

Points to variable to receive the new image.

Return Value

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

Discussion

You should not request image buffers further ahead of the current time than the read-ahead time specified with the kQTVisualContextExpectedReadAheadKey attribute. You may skip images by passing later times, but you may not pass an earlier time than passed to a previous call to this function.

Version Notes

Introduced in QuickTime 7 for Mac OS X and in QuickTime 7.1 for Windows.

Availability
Related Sample Code
Declared In
ImageCompression.h

QTVisualContextGetAttribute

Returns a visual context attribute.

OSStatus QTVisualContextGetAttribute (
   QTVisualContextRef visualContext,
   CFStringRef attributeKey,
   CFTypeRef *attributeValueOut
);

Parameters
visualContext

The visual context.

attributeKey

Identifier of attribute to get.

attributeValueOut

A pointer to a variable that will receive the attribute value or NULL if the attribute is not set.

Return Value

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

Discussion

This routine returns a visual context attribute.

Version Notes

Introduced in QuickTime 7 for Mac OS X and in QuickTime 7.1 for Windows.

Availability
Declared In
ImageCompression.h

QTVisualContextGetTypeID

Returns the CFTypeID for QTVisualContextRef.

CFTypeID QTVisualContextGetTypeID (
   void
);

Discussion

Use this function to test whether a CFTypeRef that extracted from a CF container such as a CFArray was a QTVisualContextRef.

Version Notes

Introduced in QuickTime 7 for Mac OS X and in QuickTime 7.1 for Windows.

Availability
Declared In
ImageCompression.h

QTVisualContextIsNewImageAvailable

Queries whether a new image is available for a given time.

Boolean QTVisualContextIsNewImageAvailable (
   QTVisualContextRef visualContext,
   const CVTimeStamp *timeStamp
);

Parameters
visualContext

The visual context.

timeStamp

Time in question.

Return Value

A Boolean.

Discussion

This function returns TRUE if there is a image available for the specified time that is different from the last image retrieved from QTVisualContextCopyImageForTime.

Version Notes

Introduced in QuickTime 7 for Mac OS X and in QuickTime 7.1 for Windows.

Availability
Related Sample Code
Declared In
ImageCompression.h

QTVisualContextRelease

Releases a visual context object.

void QTVisualContextRelease (
   QTVisualContextRef visualContext
);

Parameters
visualContext

A reference to a visual context object. If you pass NULL, nothing happens.

Discussion

When the retain count decreases to zero, the visual context is disposed.

Version Notes

Introduced in QuickTime 7 for Mac OS X and in QuickTime 7.1 for Windows.

Availability
Related Sample Code
Declared In
ImageCompression.h

QTVisualContextRetain

Retains a visual context object.

QTVisualContextRef QTVisualContextRetain (
   QTVisualContextRef visualContext
);

Parameters
visualContext

A reference to a visual context object. If you pass NULL, nothing happens.

Return Value

On return, a reference to the same visual context object, for convenience.

Version Notes

Introduced in QuickTime 7 for Mac OS X and in QuickTime 7.1 for Windows.

Availability
Related Sample Code
Declared In
ImageCompression.h

QTVisualContextSetAttribute

Sets a visual context attribute.

OSStatus QTVisualContextSetAttribute (
   QTVisualContextRef visualContext,
   CFStringRef attributeKey,
   CFTypeRef attributeValue
);

Parameters
visualContext

The visual context.

attributeKey

Identifier of attribute to set.

attributeValue

The value of the attribute to set, or NULL to remove a value.

Return Value

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

Version Notes

Introduced in QuickTime 7 for Mac OS X and in QuickTime 7.1 for Windows.

Availability
Related Sample Code
Declared In
ImageCompression.h

QTVisualContextSetImageAvailableCallback

Installs a user-defined callback to receive notifications when a new image becomes available.

OSStatus QTVisualContextSetImageAvailableCallback (
   QTVisualContextRef visualContext,
   QTVisualContextImageAvailableCallback imageAvailableCallback,
   void *refCon
);

Parameters
visualContext

The visual context invoking the callback.

imageAvailableCallback

Time for which a new image has become available. May be NULL.

refCon

A user-defined value passed to QTImageAvailableCallback.

Return Value

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

Discussion

Due to unpredictible activity, such as user seeks or the arrival of streaming video packets from a network, new images may become available for times supposedly occupied by previous images. Applications using the CoreVideo display link to drive rendering probably do not need to install a callback of this type, since they will already be checking for new images at a sufficient rate.

Version Notes

Introduced in QuickTime 7 for Mac OS X and in QuickTime 7.1 for Windows.

Availability
Related Sample Code
Declared In
ImageCompression.h

QTVisualContextTask

Enables the visual context to release internally held resources for later use.

void QTVisualContextTask (
   QTVisualContextRef visualContext
);

Parameters
visualContext

The visual context.

Discussion

For optimal resource management, this function should be called in every rendering pass. It should be called after old images have been released, new images have been used and all rendering has been flushed to the screen. The call is not mandatory.

Version Notes

Introduced in QuickTime 7

Availability
Related Sample Code
Declared In
ImageCompression.h

RemoveMovieApertureModeDimensions

Removes aperture mode dimension information from a movie.

OSErr RemoveMovieApertureModeDimensions (
   Movie movie
);

Parameters
movie

The movie.

Discussion

This function removes aperture mode dimension information from a movie’s tracks. It does not attempt to modify sample descriptions, so it may not completely reverse the effect of GenerateMovieApertureModeDimensions. It sets the kQTVisualPropertyID_HasApertureModeDimensions property to FALSE.

Version Notes

Introduced in QuickTime 7.1

Availability
Declared In
Movies.h

RemoveTrackApertureModeDimensions

Removes aperture mode dimension information from a track.

OSErr RemoveTrackApertureModeDimensions (
   Track track
);

Parameters
track

The track.

Discussion

This function removes aperture mode dimension information from a track. It does not attempt to modify sample descriptions, so it may not completely reverse the effect of GenerateTrackApertureModeDimensions. It sets the kQTVisualPropertyID_HasApertureModeDimensions property to FALSE.

Version Notes

Introduced in QuickTime 7.1.

Availability
Declared In
Movies.h

SCAudioFillBuffer

Used is used to pull compressed frames from the StdAudio component in kQTSCAudioPropertyID_BasicDescription format.

ComponentResult SCAudioFillBuffer (
   ComponentInstance ci,
   SCAudioInputDataProc inInputDataProc,
   void *inInputDataProcRefCon,
   UInt32 *ioOutputDataPacketSize,
   AudioBufferList *outOutputData,
   AudioStreamPacketDescription *outPacketDescription
);

Parameters
ci

The client’s connection to a StdAudio Compression component.

inInputDataProc

The proc address of the function that will be called to supply data in the kQTSCAudioPropertyID_InputBasicDescription format to SCAudio.

inInputDataProcRefCon

The client refcon that will be passed to the user-provided SCAudioInputDataProc function.

ioOutputDataPacketSize

On input, the number of desired packets. On output, the actual number of packets delivered (can be fewer than the input desired packets).

outOutputData

An AudioBufferList providing sufficiently large buffers to hold the requested number of packets.

outPacketDescription

An array of AudioStreamPacketDescriptions. If the requested output format requires external framing information––that is, a VBR format such as AAC–– allocate and pass an array of packet descriptions as large as the number of packets you are requesting.

Discussion

SCAudioFillBuffer preserves the same style API as the Core Audio AudioConverterFillComplexBuffer API, which is part of the AudioToolbox framework and resides in AudioConverter.h.

This function has the same parameters as AudioConverterFillComplexBuffer, but internally it has an audio converter, a matrix mixer, and another audio converter. It is based on a “pull” model: You pull on the audio converter for some output, and specify the buffer in which you want to put it. You have already configured the format that it is going to return to you. You also provide it with an input proc and it will call back that input proc and specify however many samples of audio you have. For example, if you want five packets of AAC audio coming out the back end, and at the front end you happen to have PCM de-interleaved, the routine will ask you for the samples. The difference is you can now have different numbers of channels going in or out. For example, at the same time you are doing the compression from PCM to AAC, you can also go from 5.1 to stereo.

SCAudioFillBuffer is used to pull compressed frames from the StdAudio component in kQTSCAudioPropertyID_BasicDescription format. The StdAudio component can perform any combination of decompression/mixing/compression, combining the facilities of Core Audio AudioConverters and Matrix Mixer AudioUnits. The behavior of the SCAudioFillBuffer call (signalling end of data, and so on) is identical to the AudioConverter's AudioConverterFillComplexBuffer API.

One important difference between the AudioConverter and SCAudio component is that the SCAudio compression APIs can do mixing as well as n -> n channels conversion. If you want to compress, decompress, or transcode audio using the SCAudioFillBuffer interface, you configure the StandardCompressionSubTypeAudio component with the desired input and output formats (or use the SCRequestImageSettings API to present a dialog and let a user select an output format), then you call SCAudioFillBuffer, providing an SCAudioInputDataProc callback, which is called for audio in the specified source format.

Version Notes

Introduced in QuickTime 7.1 for Windows and QuickTime 7 for Mac OS X.

Availability
Related Sample Code
Declared In
QuickTimeComponents.h

SetMovieVisualContext

Targets a movie to render into a visual context.

OSStatus SetMovieVisualContext (
   Movie movie,
   QTVisualContextRef visualContext
);

Parameters
movie

The movie.

visualContext

The visual context that the movie will render into. May be NULL.

Return Value

An error code. Returns noErr if there is no error. Returns memFullErr if memory cannot be allocated. Returns kQTVisualContextNotAllowed if the movie is not able to render using a visual context. Returns paramErr if the movie is NULL.

Discussion

When SetMovieVisualContext succeeds, it will retain the QTVisualContext object for its own use. If visualContext is NULL, the movie will not render any visual media. SetMovieVisualContext will fail if a different movie is already using the visual context, so you should first disassociate the other movie by calling SetMovieVisualContext with a NULL visualContext.

Special Considerations

Note that calling SetMovieGWorld on a movie that is connected to a visual context will work, but it may still keep a reference to the visual context. If you wish to completely disconnect the visual context, make sure to first call SetMovieVisualContext with a NULL visualContext.

Version Notes

Introduced in QuickTime 7 for Mac OS X and in QuickTime 7.1 for Windows.

Availability
Related Sample Code
Declared In
Movies.h

SetTrackApertureModeDimensionsUsingSampleDescription

Sets a track’s aperture mode dimensions using values calculated using a sample description.

ComponentResult ADD_MEDIA_BASENAME() SetTrackApertureModeDimensionsUsingSampleDescription

Parameters
track

The track.

sampleDesc

The sample description handle.

Discussion

This function should be used to add information needed to support aperture modes to newly created tracks. This information is calculated using the given sample description. If sampleDesc is NULL, the track’s first sample description is used.

Version Notes

Introduced in QuickTime 7.1.

Availability
Declared In
Movies.h

© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-08-14)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.