Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Video Components Reference for QuickTime

Framework
Frameworks/QuickTime.framework
Declared in
IOMacOSTypes.h
IOMacOSVideo.h
QuickTimeComponents.h
QuickdrawTypes.h

Overview

Video digitizer components convert video input into digitized color images that are compatible with the graphics system of a computer.

Functions by Task

Controlling Analog Video

Controlling Color

Controlling Compressed Source Devices

Controlling Digitization

Controlling the Video Output Display Mode

Controlling Video Output

Finding Components Associated With a Video Output

Getting Information About Video Digitizer Components

Registering the Name of Video Output Software

Saving and Restoring Component Configurations

Selecting an Input Source

Selectively Displaying Video

Setting Source Characteristics

Setting Video Destinations

Video Clipping

Video Digitizer Utilities

Supporting Functions

Functions

QTVideoOutputBaseSetEchoPort

Called on the base video output component to inform it about a change in the echo port.

ComponentResult QTVideoOutputBaseSetEchoPort (
   QTVideoOutputComponent vo,
   CGrafPtr echoPort
);

Parameters
vo

The instance of a video output component for this request. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

echoPort

The window on the computer's desktop in which to display the video.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputBegin

Obtains exclusive access to the video hardware controlled by a video output component.

ComponentResult QTVideoOutputBegin (
   QTVideoOutputComponent vo
);

Parameters
vo

The instance of a video output component. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

Return Value

See Error Codes. Returns noErr if there is no error. If this function returns the videoOutputInUseErr result code that indicates that the video hardware is currently in use, your software can get the name of the application or other software that is using the hardware by calling QTVideoOutputGetCurrentClientName. You can then display an alert to the user that says that the video hardware is in use and specifies the name of the software using the video hardware.

Discussion

When your software calls this function, the video output component acquires exclusive access to the video hardware controlled by the specified video output component or returns the videoOutputInUseErr result code if the video hardware is currently in use. If the video hardware is available, the video output component also enables the display mode last set with QTVideoOutputSetDisplayMode and enables the video settings, if any, that were most recently specified by the user in a custom video configuration dialog box. If the video output component supports QTVideoOutputCustomConfigureDisplay, your software can call the function to display a custom video configuration dialog box. When your software no longer needs the video output component, release it by calling QTVideoOutputEnd.

Special Considerations

If your software needs to change the display mode, it must change it before calling this function. It cannot change the display mode between calls to this function and to QTVideoOutputEnd.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputCopyIndAudioOutputDeviceUID

Identifies the audio device being used by a video output component.

ComponentResult QTVideoOutputCopyIndAudioOutputDeviceUID (
   QTVideoOutputComponent vo,
   long index,
   CFStringRef *audioDeviceUID
);

Parameters
vo

Video output component whose audio output is being asked about.

index

Which of video output component's audio outputs is being asked about.

audioDeviceUID

Returned unique identifier for the audio device. If the UID is NIL, the movie is playing to the default device.

Return Value

See Error Codes in the QuickTime API Reference. Returns noErr if there is no error. Returns badComponentInstance if vo is not a valid ComponentInstance. Returns badComponentSelector if vo doesn't support this function. Returns paramErr if audioDeviceUID is NIL, or if there is no device with the passed index.

Discussion

The returned audioDeviceUID has already been retained for the caller, using standard Core Foundation copy semantics.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputCustomConfigureDisplay

Displays a custom video configuration dialog box, which can include settings that are specific to the video device controlled by the video output component.

ComponentResult QTVideoOutputCustomConfigureDisplay (
   QTVideoOutputComponent vo,
   ModalFilterUPP filter
);

Parameters
vo

The instance of a video output component for this request. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

filter

A ModalFilterProc callback for the video output component to use for the dialog box. The filter allows the software to process events while the dialog box is displayed.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Your software can determine if a video output component supports this function by calling ComponentFunctionImplemented for the component with the routine selector kQTVideoOutputCustomConfigureDisplaySelect.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputEnd

Releases access to the video hardware controlled by a video output component.

ComponentResult QTVideoOutputEnd (
   QTVideoOutputComponent vo
);

Parameters
vo

The instance of a video output component. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Your software should release access to a video output component as soon as it is done using the video hardware controlled by the component. If you close the instance of a video output component that currently has exclusive access to video hardware, the video output component automatically calls this function to release the hardware.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputGetClientName

Obtains the name of the application or other software that is registered with an instance of a video output component.

ComponentResult QTVideoOutputGetClientName (
   QTVideoOutputComponent vo,
   Str255 str
);

Parameters
vo

The instance of a video output component for the request. Your software obtains this reference when it calls OpenComponent or OpenDefaultComponent.

str

The name of the application or other software that is registered with the component instance.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputGetClock

Returns a pointer to the clock component associated with the video output component.

ComponentResult QTVideoOutputGetClock (
   QTVideoOutputComponent vo,
   ComponentInstance *clock
);

Parameters
vo

The instance of a video output component for this request. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

clock

A pointer to the clock component associated with the video output component.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Your software can use the clock component returned by this function to synchronize video and sound for a movie to the rate of the display. To associate the instance of the clock component with a movie, call SetMovieMasterClock. Because a change to the display mode could affect a clock component, your software should call this function only between calls to QTVideoOutputBegin and QTVideoOutputEnd, when it is not possible to change the display mode.

Special Considerations

When your software calls QTVideoOutputEnd, the video output component disposes of the instance of the clock component returned by this function. Because of this, software that uses the clock to control a movie must reset the clock for the movie to the default clock, by calling SetMovieMasterClock with NIL as the value of the clock component, before calling QTVideoOutputEnd.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputGetCurrentClientName

Returns the name of the software, if any, that has exclusive access to the video hardware controlled by a video output component.

ComponentResult QTVideoOutputGetCurrentClientName (
   QTVideoOutputComponent vo,
   Str255 str
);

Parameters
vo

The instance of a video output component for this request. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

str

The name of the software that has exclusive access to the video hardware controlled by a video output component, or a zero-length string if no software currently has access.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

If video hardware is unavailable because other software is using it, your software can inform users by getting the name of the software with this function and displaying the name in an alert box.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputGetDisplayMode

Returns the current display mode for a video output component.

ComponentResult QTVideoOutputGetDisplayMode (
   QTVideoOutputComponent vo,
   long *displayModeID
);

Parameters
vo

The instance of a video output component. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

displayModeID

A pointer to the ID of the current display mode, or 0 if no display mode has been selected. The ID specifies a QT atom of type kQTVODisplayModeItem in the QT atom container returned by QTVideoOutputGetDisplayModeList.

Return Value

See Error Codes. Returns noErr if there is no error. If this function returns an atom ID of 0, it indicates that no display mode has been selected.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputGetDisplayModeList

Returns a list of the display modes supported by a video output component.

ComponentResult QTVideoOutputGetDisplayModeList (
   QTVideoOutputComponent vo,
   QTAtomContainer *outputs
);

Parameters
vo

The instance of a video output component. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

outputs

A pointer to the QT atom container that lists the video modes supported by this component.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

After your software calls this function, it must dispose of the QT atom container returned by the function by calling QTDisposeAtomContainer.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputGetGWorld

Returns a pointer to the graphics world used by a video output component.

ComponentResult QTVideoOutputGetGWorld (
   QTVideoOutputComponent vo,
   GWorldPtr *gw
);

Parameters
vo

The instance of a video output component for this request. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

gw

A pointer to the graphics world used by the video output component to display images.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

If the pixel format of the graphics world is 1, 2, 4, 8, 16, or 32, your software can use either QuickDraw or QuickTime to draw graphics to it. If the graphics world has any other pixel format, your software must use QuickTime functions draw to it. Your software can pass the pointer returned by this function to the SetMovieGWorld, DecompressSequenceBegin, DecompressSequenceBeginS, DecompressImage, and FDecompressImage functions.

Your software can call QTVideoOutputGetGWorld only between calls to QTVideoOutputBegin and QTVideoOutputEnd. When your software calls QTVideoOutputEnd, the video output component automatically disposes of the graphics world. If your software needs to use the graphics world after calling QTVideoOutputEnd, it must call this function again after the next time it calls QTVideoOutputBegin.

Special Considerations

Your software must not dispose of the graphics world used by a video output component. The video output component automatically disposes of the graphics world when your software calls QTVideoOutputEnd.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputGetGWorldParameters

Called by the base video output component as part of its implementation of QTVideoOutputGetGWorld.

ComponentResult QTVideoOutputGetGWorldParameters (
   QTVideoOutputComponent vo,
   Ptr *baseAddr,
   long *rowBytes,
   CTabHandle *colorTable
);

Parameters
vo

An instance of your video output component.

baseAddr

The address at which to display pixels. If your video output component does not display pixels, return 0 for this parameter.

rowBytes

The width of each scan line in bytes. If your video output component does not display pixels, return the width of the current display mode.

colorTable

The ColorTable structure to be used. If your video output component does not use a color table, return NIL.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function is not called by applications or other client software.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputGetIndImageDecompressor

Undocumented

ComponentResult QTVideoOutputGetIndImageDecompressor (
   QTVideoOutputComponent vo,
   long index,
   Component *codec
);

Parameters
vo

Undocumented

index

Undocumented

codec

Undocumented

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 5.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputGetIndSoundOutput

Determines which sound output components are associated with the video output component.

ComponentResult QTVideoOutputGetIndSoundOutput (
   QTVideoOutputComponent vo,
   long index,
   Component *outputComponent
);

Parameters
vo

The instance of a video output component for this request. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

index

Specifies which of the sound output components to return. The index of the first component is 1.

outputComponent

A pointer to a sound output component associated with the video output component that is specified by the index parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Your software can display sound output components returned by this function in a dialog box and let the user choose which outputs to use for movie playback.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputRestoreState

Restores the previously saved state of a video output component.

ComponentResult QTVideoOutputRestoreState (
   QTVideoOutputComponent vo,
   QTAtomContainer state
);

Parameters
vo

The instance of a video output component for this request. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

state

A QT atom container, returned earlier by QTVideoOutputSaveState, that contains state information for the video output component.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

If your software saves state information to disk, it must read the QT atom container structure from disk before calling this function. When your software restores state information for a video output component, the current display mode may change. Because of this, your software must call this function before calling QTVideoOutputBegin.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputSaveState

Saves state information for an instance of a video output component.

ComponentResult QTVideoOutputSaveState (
   QTVideoOutputComponent vo,
   QTAtomContainer *state
);

Parameters
vo

The instance of a video output component for this request. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

state

A pointer to complete information about the video output component's current configuration.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

When your software saves state information for an instance of a video output component, it can restore this information when reconnecting to the component by calling QTVideoOutputRestoreState.

Special Considerations

When your software calls this function, it must dispose of the QT atom container returned by the function by calling QTDisposeAtomContainer.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputSetClientName

Registers the name of an application or other software with an instance of a video output component.

ComponentResult QTVideoOutputSetClientName (
   QTVideoOutputComponent vo,
   ConstStr255Param str
);

Parameters
vo

The instance of a video output component for the request. Your software obtains this reference when it calls OpenComponent or OpenDefaultComponent.

str

The name of the application or other software to be registered.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The name you specify with this function can later be used by QTVideoOutputGetCurrentClientName to specify which software has exclusive access to the video output device controlled by the component.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputSetDisplayMode

Specifies the display mode to be used by a video output component.

ComponentResult QTVideoOutputSetDisplayMode (
   QTVideoOutputComponent vo,
   long displayModeID
);

Parameters
vo

The instance of a video output component for the request. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

displayModeID

The ID of the display mode to use. The ID specifies a QT atom of type kQTVODisplayModeItem in the QT atom container returned by QTVideoOutputGetDisplayModeList.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

When software changes the display mode with this function, the change does not take effect until the next time the software calls QTVideoOutputBegin for the video output component. This lets the software change other output settings before displaying the video.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

QTVideoOutputSetEchoPort

Specifies a window on the desktop in which to display video sent to the device.

ComponentResult QTVideoOutputSetEchoPort (
   QTVideoOutputComponent vo,
   CGrafPtr echoPort
);

Parameters
vo

The instance of a video output component for this request. Your software obtains this reference when calling OpenComponent or OpenDefaultComponent.

echoPort

The window on the computer's desktop in which to display the video.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

When your software sends video to the window you specify, the video is both displayed in the window and sent to the normal output of the video output device. When an output device can display video both on an external video display and in a window on a computer's desktop, the video displayed on the desktop is often at a smaller size and/or lower frame rate.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

VDAddKeyColor

Adds a key color to a component's list of active key colors.

VideoDigitizerError VDAddKeyColor (
   VideoDigitizerComponent ci,
   long *index
);

Parameters
ci

The video digitizer component for the request. Applications obtain this reference from OpenComponent or OpenDefaultComponent.

index

A pointer to the color to add to the key color list. The value of the index field corresponds to a color in the current color lookup table.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

VDCaptureStateChanging

Provides process information from a sequence grabber component to the VDIG.

VideoDigitizerError VDCaptureStateChanging (
   VideoDigitizerComponent ci,
   UInt32 inStateFlags
);

Parameters
ci

The video digitizer component for the request. Applications obtain this reference from OpenComponent or OpenDefaultComponent.

inStateFlags

Constants (see below) that tell the VDIG what is about to happen. See these constants:

  • vdFlagCaptureStarting

  • vdFlagCaptureStopping

  • vdFlagCaptureIsForPreview

  • vdFlagCaptureIsForRecord

  • vdFlagCaptureLowLatency

  • vdFlagCaptureAlwaysUseTimeBase

Return Value

An error return of type ComponentResult. See Error Codes. Returns noErr if there is no error.

Discussion

It has long been a problem for VDIG writers that the sequence grabber can make a series of calls to a VDIG and it is not always clear what their intent is. This function lets you provide additional information about what is happening at the sequence grabber level to the VDIG, so it can take this into account. In particular, the settings bracketing calls are designed for the VDIG to update a series of parameters without reinitializing.

Version Notes

Introduced in QuickTime 6.

Availability
Declared In
QuickTimeComponents.h

VDClearClipRgn

Disables all or part of a clipping region that was previously set with VDSetClipRgn.

VideoDigitizerError VDClearClipRgn (
   VideoDigitizerComponent ci,
   RgnHandle clipRegion
);

Parameters
ci

The video digitizer component for the request. Applications obtain this reference from OpenComponent or OpenDefaultComponent.

clipRegion

A handle to a MacRegion structure that defines the clipping region to clear. This region must correspond to all or part of the clipping region established previously with VDSetClipRgn.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

VDCompressDone

Determines whether the video digitizer has finished digitizing and compressing a frame of image data.

VideoDigitizerError VDCompressDone (
   VideoDigitizerComponent ci,
   UInt8 *queuedFrameCount,
   Ptr *theData,
   long *dataSize,
   UInt8 *similarity,
   TimeRecord *t
);

Parameters
ci

Identifies the application's connection to the video digitizer component. An application obtains this value from OpenComponent or OpenDefaultComponent.

queuedFrameCount

A pointer to the number of queued frames yet to be done. 0 means no frames. Some VDIGs may return 2 even if more than 2 frames are available, and some will return 1 if any number more than 0 are available.

theData

A pointer to a field that is to receive a pointer to the compressed image data. The digitizer returns a pointer that is valid in the application's current memory mode.

dataSize

A pointer to a field to receive a value indicating the number of bytes of compressed image data.

similarity

A pointer to a field to receive an indication of the relative similarity of this image to the previous image in a sequence. A value of 0 indicates that the current frame is a key frame in the sequence. A value of 255 indicates that the current frame is identical to the previous frame. Values from 1 through 254 indicate relative similarity, ranging from very different (1) to very similar (254). This field is only filled in if the temporal quality passed in with VDSetCompression is not 0; that is, if it is not frame-differenced.

t

A pointer to a TimeRecord structure. When the operation is complete, the digitizer fills in this structure with information indicating when the frame was grabbed. The time value stored in this structure is in the time base that the application sets with VDSetTimeBase.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

VDCompressOneFrameAsync

Instructs the video digitizer to digitize and compress a single frame of image data.

VideoDigitizerError VDCompressOneFrameAsync (
   VideoDigitizerComponent ci
);

Parameters
ci

Identifies the application's connection to the video digitizer component. An application obtains this value from OpenComponent or OpenDefaultComponent.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Unlike VDGrabOneFrameAsync, this function causes the video digitizer to handle all details of managing data buffers.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

VDDone

Determines if VDGrabOneFrameAsync is finished with a specific output buffer.

VideoDigitizerError VDDone (
   VideoDigitizerComponent ci,
   short buffer
);

Parameters
ci

The video digitizer component for the request. Applications obtain this reference from OpenComponent or OpenDefaultComponent.

buffer

Identifies the buffer for the operation. The value of this parameter must correspond to a valid index into the list of buffers you supply when your application calls VDSetupBuffers. This value is zero-based; that is, you must set this parameter to 0 to refer to the first buffer in the buffer list.

Return Value

Returns a long integer indicating whether the specified asynchronous frame grab is complete. If the returned value is 0, the video digitizer component is still working on the frame. If the returned value is nonzero, the digitizer component is finished with the frame and the application can perform its processing.

Discussion

Applications can determine whether a video digitizer component supports asynchronous frame grabbing by examining the output capability flags of the digitizer component, using VDGetCurrentFlags. Specifically, if the digiOutDoesAsyncGrabs flag is set to 1, the digitizer component supports both this function and VDGrabOneFrameAsync.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h